Auto-generate API documentation file (e.g. Swagger)

[brylie]

There is currently an API methods endpoint that produces a JSON-based endpoint listing.

• What would allow us automatically provide an API documentation file, in a standardized format?
• What packages or resources are available to auto-document an API, given enough user input in the API configuration file?

[stubailo]

I've actually been looking at different API documentation formats recently, and none of them seem that great.

The format returned by the API methods endpoint is the same as from a DDP publication right now, with some custom fields.

In order to provide a standardized format, we would need:

1. A new endpoint in addition to list-api that returns the right format: https://github.com/stubailo/meteor-rest/blob/devel/packages/rest/list-api.js
2. New parameters for JsonRoutes.add that let you add additional metadata
3. Functionality for Meteor.publish where you can specify which collections are being returned, and set the appropriate metadata

If you'd like to build this, I'd love to help. I don't have time to write the code myself but I don't think it would be too hard, and I can help with any design questions about it.

[brylie]

Thanks for the clarification about required steps. I will talk to our project owner about writing a documentation generator plugin for JsonRoutes.

[jykae]

About step 2, do you mean adding "metadata" in addition to "method" and "path" variables? https://github.com/stubailo/meteor-rest/blob/4f8260d8a6501127b8613fe63dfaab408fd5c6b7/packages/json-routes/json-routes.js#L56

I think would be good to let API user to select format as parameter to "list-api" endpoint? (eg. swagger, raml etc.)

What would be the best suited way to work contribution? Forking to our organization, making changes and contributing back to meteor-rest? I think forks can be compared. We could keep discussion thread here.

[jykae]

I start working on this under our Apinf organization, https://github.com/apinf/meteor-rest From there I open PR for meteor-rest, when we have something initial Swagger generation working. I try to provide tests for the parts I add, as I can see you have nice initial setup with Tinytest.

[stubailo]

Thanks! For the record I would prefer something that has a plugin for swagger, rather than having a specific format hard coded in.

[jykae]

Hmm, yes. Maybe best to put my code in separate package folder, "rest-swagger" and package name, "simple:rest-swagger". Same pattern could possibly be followed for other formats.

[stubailo]

Sounds great to me. I'd love to help in any way I can.

[jykae]

If you are more familiar with json-routes already, designing how to do this on json-routes level so that it would benefit simple:rest and Restivus both. You are welcome to review my progress. We switched to Restivus yesterday, trying first get it working with that.

[stubailo]

OK! Please let me know if you have something that I could take a look at. I think it will just be a matter of passing down some extra information to JsonRoutes.add from Restivus to make it more generic. I'm definitely interested in making any docs generation work with simple:rest as well.

[jykae]

@stubailo FYI: we don't currently have time to support simple:rest for swagger.json generation. As we decided to go with Restivus, I made swagger plugin for that https://atmospherejs.com/apinf/restivus-swagger as it is enough for our purposes.

[stubailo]

OK, thanks for letting me know! I thought the goal was more to do something auto-generated, since I find that manual documentation gets out of date very quickly?

[brylie]

I thought the goal was more to do something auto-generated, since I find that manual documentation gets out of date very quickly?

We do want to auto-generate as much of the documentation as possible, but there are certain fields (such as description) that need a human touch.