Writing REST API Documentation

stunmer

I am building a REST api and I need to document it clearly.

Anyone have any good info / tutorials on how to write and structure good clean documentation?

Graham

What are you writing your API in?

It might be worth looking at some of the API doc generators:

https://github.com/apidoc/apidoc
http://swagger.io/

stunmer

Cheers,

Writing the API in PHP but looking for language independent JSON API documentation.

Graham

The documentation produced by the API doc generators will be language independent.

It's the production of the documentation itself that's automated. You make sure your code is commented in a specific format, those comments are then assembled into documentation by the generators. It should mean keeping your documentation up-to date is much easier as your API evolves, also means your documentation looks better/familiar when you share it.

Johnny Jukebox

+1 for Swagger, its excellent.

henryporter

Johnny Jukebox wrote: »

+1 for Swagger, its excellent.

Agreed - the sandbox functionality is a big plus.