API Documentation generation

Hey there,

We need to generate a documentation for our new API written with jsonapi-resources (oh yeah!), authenticated with doorkeeper (OAuth2) and versioned with versionist (HTTP Header).

I have reviewed some tools (api-blueprint, apipie, swagger, slate, ...) and would like to know what's your position on them. Do you already have a preference?

It seems obvious there's already a lot of logic encapsulated inside our API resources/routes files and that we should be able to generate some documentation automagically instead of rewriting everything manually to some markdown/yaml/... files.

Do you think starting something like grape-apiary make sense? Is it too early, maybe not enough stable API yet?

Let start the discussion!

/cc @barelyknown & @dgeb If I remember well, you discuss this on a the Ruby on Rails Podcast 187

Examinez les fichiers existants de ressources/routes de l'API ainsi que les exigences de jsonapi-resources, doorkeeper et versionist. Comparez les outils mentionnés, notamment api-blueprint, apipie, Swagger, Slate et grape-apiary. Le travail est considéré comme terminé lorsqu'une approche de génération de documentation et son périmètre ont été définis d'un commun accord ; l'issue ne nomme pas de fichiers ni de tests spécifiques.