In a 250 org, I would propose to document the APIs automatically through swagger[^1] and use something like sphinx[^2] to get started for everything else. That said documentation is extra burden that ppl usually don't get credit for. Keep in mind that apart from creating the docs, the team needs to keep them up-to-date and that's a challenge as well. Adding "review documentation" in the definition of done could help.
I'm realizing that I need to specify: I'm not primarily interested in documenting APIs, more things like:
* Preferred way of doing X
* X domain uses these tables and works like this
* This is what X feature does and here's what it looks like
Most of us work in the single large codebase, and we don't have a good separation of responsibility between the pieces yet (it's a work in progress) so for now I mostly want to document what stuff exists rather than formal API documentation.
I just have to voice an opinion that swagger is not an API documentation tool. It might be a helpful tool, but it does not produce an API specification.
An API specification:
- must be diff'able with any previous version
- must have a version number
- must specify every parameter, it's range, whether it's mandatory or not, list all possible values for enumerated types, etc.
So if you use swagger, you won't be able to:
- review changes needed in your part of the system before the code is published (even in a development environment)
OpenAPI (not Swagger; that's the old name for the spec and the current name for the toolset) has all of the above functionalities. One important component is, to get the best benefit, it should be used for specification and not (just) documentation; in other words, you define the contract first and then base the various implementations (both server and client side) on it.
Unfortunately there are not many tools that support that approach; I've tried to rectify that - for Python - with Pyotr [0].
[^1]: https://swagger.io/docs/
[^2]: https://www.sphinx-doc.org/en/master/