Ask EJ : tool to generate REST api documentation?

5 up and 0 down, posted by fallanic 3961 days ago 7 comments

fallanic 3961 days ago.

Hi everybody,

does anybody know any good tool to generate the documentation of a REST api, from the comments and/or annotations of some node.js code?

Thanks!

fallanic 3961 days ago. link 2 points ▲ ▼

I ended up using apidoc, which was almost exactly was I was looking for : a really simple tool reading some annotations in my code and generating some html documentation.

Thanks all for the propositions, much appreciated!

fcambus 3961 days ago. link 2 points ▲ ▼

Maybe apiDoc? At least, it seems to match your requirements : http://apidocjs.com

trevoro 3961 days ago. link 2 points ▲ ▼

Hey,

The code to generate the documentation is in the node.git repository. See https://github.com/joyent/node/tree/master/doc.

If you're looking for a good tool for generating REST documentation I'd suggest using restdown. https://github.com/trentm/restdown

sbruchmann 3961 days ago. link 2 points ▲ ▼

If someone is looking for a bit more “mature” option:
http://raml.org/

sassyalex 3960 days ago. link 1 point ▲ ▼

Swagger

rbartoli 3961 days ago. link 1 point ▲ ▼

A good one is http://apiary.io/

They've got Markdown syntax and the service integrates amazingly with GitHub to store each change to your documentation.

awinder 3961 days ago. link 1 point ▲ ▼

http://apiblueprint.org is great.  It's not using annotations in the code, but it's documented separately in markdown.  What I've done in projects is just put markdown files next to the javascript files that contain API controllers, and then I just concatenate them together in a Grunt task before sending it through API Blueprint tools.  I'm not sure it's really a home run to couple API documentation in with the code documentation -- the audiences are really different, and your code & it's comments should be catering towards developers of the API.  But being able to put markdown files directly parallel to code I think maintains the same spirit of annotations being close to the code.

That said -- API Blueprint is great because its an open specification with a bunch of great tools built around it.  There's tools to generate html documentation, parsers to write your own tools, and tools to verify your documentation against a live instance.  That last one was the killer feature for me, as its a great integration point for a CI environment to make sure that developers on the team keep docs up to date.