Sails: Automatic generation of API documentation for models/controllers

[ryanseys]

I don't know if this is a terrible suggestion or not so feel free to bash it down if necessary (or maybe it already exists and I just overlooked it) but anyway...

It would be really neat to be able to have some nice clean documentation of the API (for my app) be automatically generated for the models and controllers I have created for my app. They could be either web accessible via the app web frontend by default or just generated on the side to read, but I think it could be a really powerful tool for developers so they can see how their own models could be used in context.

[particlebanana]

Are you talking about Sails documentation or documentation for you application?

There are a few node documentation generators out there that you can use for your app logic:

Dox by TJ uses jsdoc formatted syntax and works good with Node
Docco by Jeremy (used for Backbone and Underscore docs)

[ryanseys]

Documentation for my application. I meant more along the lines of exposing some documentation for the API functionality that Sails provides for your app when you create models, in the context of that model. This way I could create a model and controller, and then at a glance, be able to see all API functionality provided now by Sails for that model.

I feel Dox and Docco simply extract comments etc from the source code I would write, but I would prefer not writing anything, because Sails already knows what I can and cannot do with the API because they auto-generated the API.

[mphasize]

Actually it would be really, really cool if Sails could handle (at least to some extend) generating the docs for the APIs you create with Sails! The way I see it, there could be different ways to tackle this:

Within the API: We could have a blueprint action like or attributes or describe-model that exports the attributes and validation rules for a model. This might be handy for somebody implementing a client agains a SailsJS API to gain a better understanding.
I've also seen one API in the wild, where you could call a /route/action.json and would receive the data, but then you could also call /route/action.api and you would see a webpage explaining the API in question.

Doc Generation: This would probably be a Grunt task running as part of the build or deploy process. It would generate documentation on your controllers and models by combining inline doc-blocks and inherent knowledge about the API.

I tried using grunt-dox today, but unfortunately I would only get documentation for the "export" call in controllers and models instead of anything making a little more sense on the first level.

Would be great to discuss this further!
Cheers
Marcus

[mikermcneil]

This is something that's very interesting to us. Keep an eye out :)

[carlospliego]

someone create an npm module!!

[malikba]

@mikermcneil Any suggestions for beginning such a project ? I've seen StrongLoop has an API explorer. It could be a good idea to develop the same kind of tool.

[RWOverdijk]

I was working on this a while back but never finished it... What I did, was let the server lift, fetch all registered routes and then pull docblocks from the code, to document them.

I'll probably not be able to work on this for a while, but if anyone wants to run with the concept, feel free.

[leejt489]

Also very interested in this. @RWOverdijk can you share your code? I'm still learning Sails / Express / Node, but I could take a look.

[leejt489]

@RWOverdijk how do you fetch all registered routes? I'm starting to play with a node package.

Not sure if I should go the route of parsing config files and controller options like sails does to determine the API endpoints to document, or if I should go through the sails global object for registered routes.

I kind of like the former as it allows for greater flexibility and running from the command line when a sails server is not necessarily lifted, though the latter seems to be more DRY.

[camsjams]

@leejt489 any update on your generator package?

[tilomitra]

Any update on this?

[RWOverdijk]

@leejt489 https://github.com/Barque/CrowsNest/blob/master/api/controllers/DocsController.js

I was going to pick this back up, but if you're already on it you can go for it.

[JumpLink]

I use dox to generate my docs and have made good experiences with it.
Currently it is strong in development, but already looks very good.
If interested, we could outsource my DocsController to a separate module, together :)

[pmoelgaard]

@JumpLink I'm interested in what you did, is it still something you are doing ?

[joshuamarquez]

maybe an integration with RAML or API Blueprint

[simonmilz]

+1

[irjencup]

+1

[paulogdm]

+1

[abhisheksoni27]

Any news?