Echo JS 0.11.0

fallanic 1706 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?


fallanic 1706 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!
rbartoli 1706 days ago. link 1 point
A good one is

They've got Markdown syntax and the service integrates amazingly with GitHub to store each change to your documentation.
awinder 1706 days ago. link 1 point 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.