SOsolodev1·Oct 5, 2020
Adhering to OpenApi 3.0 spec https://swagger.io/docs/specification/about/ you will be able to take advantage of plenty of tools available to you, regardless of the programming language/framework chosen to build your software.
It's not always possible or desirable to have back-end models and controllers auto-generated from OpenApi spec, but still I totally recommend to make an extra effort to keep documentation and API in sync since day 1 as API is evolving.
Document an API it's definitely not an easy task, but it pays off - specially if you plan to have third-party developers consuming your API in the future beyond your own engineering team.
Some important points I try to be disciplined about, based on my own experience building APIs in C#, Delphi, Go, Java, Node.js, PHP, Python and Ruby:
1) Document your API from day 1
2) Update your API
Read the rest
docs every time you commit a new change to your models/controllers/endpoints
3) Test your API docs against your actual implementation. Dredd is a great tool for that: https://github.com/apiaryio/dredd
4) Build an API client from day one (web app, command line app, desktop app, whatever), and use it for testing the consumption of your API endpoints, and update it every time your API changes
* Benefits:
you're gonna have a perception of the developer experience that your API users are going to have when consuming it, and very likely that will bring you some insights on opportunities to make things simpler or better documented (header params, query params, request payloads, endpoints signature, response status codes, ...)