News for hackers. Stuff that matters.
Re:Ask HN: Back-end team does not document their APIs. How d... by tedmiston on Tuesday October 11, 2016 @12:37PM (#12685985)
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

[2]: http://marcgibbons.github.io/django-rest-swagger/

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

Re:Ask HN: Back-end team does not document their APIs. How d... by mipmap04 on Tuesday October 11, 2016 @03:04PM (#12687525)
+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.