API Documentation generation

[thibaudgg]

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

[lgebhardt]

@thibaudgg Thanks for getting this discussion started. I've had the idea of generating the documentation from the resource definitions and routes, but I haven't taken the next step of looking at tools to help do it. I'll try to review the tools soon. I'd like to get a list of requirements, which should help narrow the choices down.

[thibaudgg]

@lgebhardt awesome, I think I see two categories here:

1. Separated documentation

Most of them are like that (api-blueprint, swagger and slate). JR could offer a one-time generator/scaffolder for bootstrapping the documentation file from the resources/routes content. The downside is that if you update your API you'll need to update your documentation manually afterward.

2. Method annotation

JR could automatically extend/annotate it's API endpoints following apipie-rails DSL. This could be overwritten by annotating manually JR controller methods.

Personal notes:

• I'm not a big fan of how look apiepie generated docs: https://github.com/Apipie/apipie-rails#screenshots
• I really like the idea of being able to use the documentation to test our API (Dredd, Dredd::Rack and Vigia.
• API blueprint seems the most advanced ecosystem with a lot of tools around it (http://apiary.io, https://apiblueprint.org)

[john-griffin]

Great timing, we are looking to document our jsonapi-resources API at the moment.

I have been working on a spike that walks the routes and resources and outputs swagger 2.0 json format. The nice thing about this approach is that the routes and resources document themselves and the docs never get out of sync with the implementation. I have been able to add descriptions to attributes by providing options e.g.:

attribute :first_name, description: 'The first name of the user'

This can then be pulled out in my generator using ._attribute_options.

My spike is very rough but I can already see having this kind of thing supported as a core part of jsonapi-resources would be killer.

[thibaudgg]

@john-griffin I'm interested to know the reason for Swagger over Blueprint, is there uniq feature not available elsewhere? (I still don't made a final choice). Thanks!

[john-griffin]

It was mostly due to using it in the past and preferring the interface provided by Swagger UI. I'm sure Blueprint offers equivalent features and an output format could be produced in a similar manner.

[thibaudgg]

@john-griffin great, thanks for the feedback!

[john-griffin]

Based on this discussion I took a look at API Blueprint. They have only recently added support for attribute descriptions. As far as I can tell it does not currently support nested or dasherized attributes in those descriptions. As both are required for JSON API format I don't see a way of moving forward with that spec.

[thibaudgg]

@john-griffin bummer, thanks for having a look!

[john-griffin]

We decided to go with slate in the end and manually write our docs. Auto generation sounds great and gets you started really quickly but there are a lot of rough edges and it's very inflexible.

What would be useful is a generic JSON API validator or documentation starter. That wouldn't need to live in the JR project as it should work against any server that provides the spec.

[thibaudgg]

@john-griffin Thanks I'll give a deeper look to slate. At first I got the feeling that having a completely on-the-side docs would be more risky as it could tend to become out of sync. But maybe it's the simpler approach.

[lgebhardt]

I like Slate's approach of making the documentation a public git repository. Particularly the option to allow pull requests. But allowing the public to contribute to the documentation is at odds with keeping it in the codebase if the codebase is private.

I also like the idea of generating the docs from the code because it would be easy to keep the documentation up to date as the code changes. However that has the side effect that you can't update the documentation without updating the code. Even with testing there is a small risk of problems with any deployment.

What would be useful is a generic JSON API validator or documentation starter. That wouldn't need to live in the JR project as it should work against any server that provides the spec.

This might be the ideal for my use.

Thanks I'll give a deeper look to slate. At first I got the feeling that having a completely on-the-side docs would be more risky as it could tend to become out of sync. But maybe it's simpler approach.

I'm coming to the same conclusion that it might be the simpler approach.

[brettchalupa]

This is tangentially related to this issue, so I wanted to share it for those going down the Slate path.

The library that Slate uses does not highlight JSON API http code blocks as JSON, so I proposed adding support for it here: https://github.com/jneen/rouge/pull/259 If it lands, be sure to update the Slate repo in use to use the latest version of rogue (the one in master on the repo is a few versions behind).

@john-griffin and I are working on building an API w/ JR and documenting it with Slate, and so far, so good. We have been using Paw to build the requests and capture the responses.

It definitely feels like there could be some kind of middleware that helps in some way, but I need to noodle on it some more to define what it could be. :smile:

[thibaudgg]

@brettchalupa thanks a lot for sharing that, really helpful!

[utilityboy]

For those in the rspec camp, I've had some success with: Rspec Api Documentation. There are a few nuances, but it's decent for keeping tests and docs in sync. Happy to answer any questions about my experiences with it.

[thibaudgg]

@bjubinville thanks for your comment. So far I found the html output of RSpec API doc not that nice, did you apply some custom CSS?

[slaskis]

I've been using RAML to document my API and I like it, it's rather powerful and has some tooling which generates a series of tests to run against the definition which can be nice.

[xdmx]

We also use rspec api documentation for our project and we love it, especially having in sync the doc, tests and api, without increasing the work

We use it with apitome which improves the api style

[thibaudgg]

@xdmx could you share a public link so we can see an apitome style example?

[barelyknown]

I made an example that included generated docs using rspec_api_documentation for a talk at Boston Ember earlier this month. Here's the code and the documentation. It would be straight forward to fiddle with it to try different styles.

[thibaudgg]

@barelyknown thanks! I'll have a look. This docs is using the default html export right? We're currently using slate and we really like its nice out-of-the-box style/design. The only think that prevent me to try rspec_api_documentation is its non-style by default. Would be nice to have an rspec_api_documentation => slate export tool.

Oh btw, :+1: for Ruby On Rails podcast season 2, I really like it so far!

[barelyknown]

Yeah, that's the default.

The design of slate looks nice. I haven't looked at all of the formatting options that you could use, but I'm pretty sure that you can make it look quite nice. If you figure that out, submit a PR to the json-api-example repo (if you have the time).

Thanks for the nice words about the podcast. I appreciate it.

[bajalovic]

Any update on this? Is there going to be a documentation generation?

[toobulkeh]

Interesting discussion. I've been heavily using API Blueprint for the past few months and have found APIary and API Blueprint to both be very frustrating. After evaluating Swagger and slate, I believe I'm going to give slate a try next. I'll be duplicating the repo for a true fork, but yet-another-dependency in our tool chain. Thanks for the comments and having this discussion publicly!

[utilityboy]

@toobulkeh your comment came in just as I was working on this myself. @thibaudgg sorry to have missed your question from earlier, but it looks like you've got things working with Apitome + RAD now.

After several months, I still like the combination of Apitome + RAD myself. Our API is private, so Apitome looks nice enough for any of our customers just looking for documentation. I've yet to have a customer that is unable to figure things out after going through our docs.

I've come up with a little set of RAD helpers which complements JSONAPI Resources. If there's interest, I can tidy that up and drop a gist in here.

[brettchalupa]

@toobulkeh After months have passed and working on a new project, I have been using Apitome + rspec_api_documentation (RAD) w/ JSONAPI::Resources like @bjubinville is. It has been working well, and it is only for internal use. Getting it setup and configured was pretty straight-forward, and I also contributed to Apitome to support remote file loading so the docs can be hosted on AWS S3 (https://github.com/modeset/apitome/pull/59).

If I started a new Rails project w/ JSONAPI::Resources, I think I would choose RAD after having used Slate and RAD. The fact that RAD docs are specs makes maintaining them a bit easier, and having it be closely coupled to the project makes the workflow of updating the docs more natural.

[toobulkeh]

Very good points. On this current project I'm playing a middleman approach where there are 2 developers on either side (one backend, one frontend) so our workflow is drastically different since I personally am not writing the backend. It's an interesting experience (to say the least) and requires a separation between the documentation and the testing, which excludes us from RAD. While this is an odd project, we'll probably continue to MVP on Rails and we might continue to use Ember (though the jury is still out on that one) so RAD is a very real possibility in the near future. Thanks for the reference!

[vrybas]

Does anyone have good examples of public JSONAPI-compliant API documentation, except for sample apps?

[nickurban]

@utilityboy I'm going to take you up on your offer, even though it's almost a year old now :)

When using RAD, how do you write parameters for creating/updating resource?

I've tried doing things like

with_options scope: [:data, :attributes] do
    parameter :name
end

But it seems kinda messy. And it's worse when specifying a bunch of relationships.

I'm thinking about trying to add a helper to succinctly express these kind of redundant nested structures, but I'd love to see how you're doing it.

Thanks!

[GeekOnCoffee]

I'd like to revisit this. I started down the path of using apipie, but it felt like a TON of extra work given the clear definitions I'm already giving.

My ideal output would be a swagger file (or similar) that I could load into Apiary so as I'm updating the API, consumers can see it as well.

Swagger might not be an ideal format, and something entirely custom would work as well, maybe an HTML view that breaks out each controller, the resource it exposes, any that can be included, all their attributes, filters, etc.

[toobulkeh]

Here's something new: https://jsonapi-suite.github.io/jsonapi_suite/

[GeekOnCoffee]

I spent a bit of time trying to get that working, but looks like it's not an easy plug and play with jsonapi-resources.

[superiorlu]

i write gem https://github.com/superiorlu/jsonapi-swagger generate swagger.json through jsonapi resources

[s892307]

Is there a plan to add Swagger support for this gem? Seems like rswag is the most popular API docs tool so it would be great if these two were compatible.

@superiorlu - looks like your gem is no longer maintained?

[satokenta940]

API document generation, you can try: https://apidog.com/