Re:Ask HN: Back-end team does not document their APIs. How d...
by wing328hk on Tuesday October 11, 2016 @10:46PM
(#12690107)
There are other tools/plug-ins to generate OpenAPI/Swagger spec (1.2 or 2.0) based on annotations in the code. Please refer to http://swagger.io/open-source-integrations/ for more information.
If the REST API is documented in OpenAPI/Swagger spec, you can then use Swagger Codegen [1] to automatically generate API clients in Java, C#, Javascript, Typescript, Ruby, ObjC, Swift and more.
[1]: https://github.com/swagger-api/swagger-codegen
Disclosure: I'm a top contributor to Swagger Codegen
One way to make API documentation easy is to generate it from code rather than write a doc manually. This can pull from class and method comments to add description to your endpoints (if those comments exist and are relevant), but even if they aren't there you'll still have access to the endpoints and the input/output.
I'm not sure what your tech stack is but here's an example using Django w/ Django Rest Framework. You can use Swagger [1] for docs / a browsable interface to the API. Then you can use an integration like Django Rest Swagger [2] to automate most of the work.
[1]: http://swagger.io
[2]: http://marcgibbons.github.io/django-rest-swagger/