7 ms·

Besides convincing your backend team that sharing how to communicate with the API in a structured way is important, one bit of advice in general is to make it e

Besides convincing your backend team that sharing how to communicate with the API in a structured way is important, one bit of advice in general is to make it easy. 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 http://swagger.io [2]: http://marcgibbons.github.io/django-rest-swagger/ http://marcgibbons.github.io/django-rest-swagger/

mipmap04 10y ago
+1 for swagger. We are a C# shop and it's awesome how our XML comments flow into the docs seamlessly. Makes documentation almost zero extra work.
wing328hk 10y ago
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/ 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 https://github.com/swagger-api/swagger-codegen Disclosure: I'm a top contributor to Swagger Codegen