OpenAPI documentation generation with rswag specs

[casaper]

Pitch

Create a generated OpenAPI documentation using the rswag gem.

This gem allows to not only generate the OpenAPI schema by writing special rswag request specs. It also allows generating the documentation OpenAPI schema, using exactly these specs.

Motivation

The only documentation I can find on API responses, seems to be things like the entities section (e.g. Account in account.md).

This is not what I'd expect to find, when I'm looking for a proper API documentation.

If I were to start writing any kind of application consuming the mastodon API's, I'd ask for a valid and up to date OpenAPI schema as the first thing.

With a valid OpenAPI-Schema, I can:

• create automated tests for the backend's schema correctness (I know what I get)
• generate code for an API consumer application
  • in many technologies out there
  • To have a test, development or other mock API server for my application
  • have types and request code, in order to access the backend code
  • update all the formers to changes that came with the schema in a proper manner
• see and try out requests using the OpenAPI-UI or many other utilities out there
• convert the schema to use with other utilities — e.g. Postman or many others
• have a standardized commonly accepted industry standard documentation for the API

With the current api documentation in mastodon/documentation I can't:

• know if that documentation actually matches the API found in the rails app – There is zero verification
• use any of the formerly mentioned generation tools

Demonstrate intention

• spec/requests/api/v1/reports_spec.rb
  • resulting in OpenApi schema output
• spec/requests/api/v1/accounts/statuses_spec.rb
  • resulting in OpenAPI schema output

ReDoc Rendering of the schema

Duplicate or not

Some may see this issue as a duplicate of #1404
I, personally, don't see is as that, as long as the other issue doesn't specify the use of rswag and testing of the OpenAPI schema against the endpoints.

[Zmote]

Agreed, this would make development easier and more accessible and would give us an accurate API.

[moritzheiber]

Another huge advantage would be auto-generated, testable (!) documentation (i.e. its examples are tested as well). I agree that generating a spec, especially for an publicly interesting application such as Mastodon, should be considered an industry best practice, and it’d be vital to its continued success and to maintain relevance.

Previous attempts at creating a general spec (OpenAPI/Swagger) were met with disinterested by the core folks (as late as 2021, so before I’d touch any code regarding this (assuming we’d be using rswag) I’d want a strong commitment that an OpenAPI spec is

• wanted
• its advantages understood and appreciated
• it’ll be actively maintained and extended by all of the core team, not just a few outsiders
• that it’ll serve as the main source of truth for API information and documentation going forward

Anything below that threshold, given the busy nature of this project, is just not realistic.

[fadookie]

Duplicate of #1404 ?

But I agree this is badly needed. Thanks for the detailed write-up.

[casaper]

@moritzheiber

I agree with all you state. Especially to:

that it’ll serve as the main source of truth for API information and documentation going forward

And

it’ll be actively maintained and extended by all of the core team, not just a few outsiders

I'd specify that outsiders like me could do the start-up effort, until the current spec has a more or less complete coverage of the existing API's.
The Core team would have to use and extend/modify the specs and docs according to the changes they make.

I created a draft PR #20607 in order to clarify a bit what I have in mind.
It has a very basic rswag setup, and generated specs for all API controllers in there.

Demonstrate intention with:

• spec/requests/api/v1/reports_spec.rb
• resulting in OpenApi path definition

[casaper]

@fadookie

Duplicate of #1404 ?

IMHO it is not a duplicate, because:

• It is from 2017 and completely stale
• It does not mention the use of rswag, which is a core point of this issue here

[ineffyble]

I'd say they're very overlapping, one is just more implementation specific, but the important thing is just to ensure there's no duplicate work and that both issues are closed if a solution is implemented.

[casaper]

@ineffyble fair enough.

I did see that issue before I created mine. I did not identify my intend in that issue, so I created a new one.

If it were my issue board, I'd close an issue inactive since 2017 in 2022 in any case. Regardless if it is a duplicate or what not. But that is off topic here ;)

[nyura123]

Demonstrate intention with:

• spec/requests/api/v1/reports_spec.rb
• resulting in OpenApi path definition

in case it's useful, the draft/demo OpenApi definition above can be browsed at ReDoc

[casaper]

@nyura123

in case it's useful, the draft/demo OpenApi definition above can be browsed at ReDoc

Nice. Thx!

There is a newer version of the schema in the pr now though.

Here is the new link to ReDoc

[petecheslock]

I have been diving into Mastodon recently, and I recently wrote a blog post showing how we can use AppMap to record the Mastodon tests, and then we can use that data to export the API documentation based on the code's runtime.

https://dev.to/appmap/automatically-generating-openapi-docs-for-mastodon-42ig

The benefit here is that we don't need to add additional code with rswag, we can simply use the existing API rspec tests and output their usage to OpenAPI.

[casaper]

Hello @petecheslock

I have been diving into Mastodon recently, and I recently wrote a blog post showing how we can use AppMap to record the Mastodon tests, and then we can use that data to export the API documentation based on the code's runtime.

This looks very interesting.
I did not yet get around reading your full blog post yet, so this is just a half-baked/informed answer.

If I'm not mistaken, your approach is to extract the schema from the debuggers call stack, when the specs are running?

That sounds quite nice, and could potentially save a lot of work, writing OpenAPI docs manually.

On the other hand, though, a few things come to my mind:

• The rswag-spec approach is only intending to generate the OpenAPI docs as a sort of by-product, actually. The main intention is to verify the API to adhere to the API-contract. AFAIS that is something your approach won't cover. It extracts as good as possible what is there, but not what should be there, right?
• paths, parameters, headers, and responses current specs do not cover (for what ever reason) will, I guess, not be covered by that approach?
• The completely automatic generation might not allow adding the extra context (descriptions etc.) a proper OpenAPI documentation requires.

Please tell me, if you think my assumptions are right or wrong, and how you see these aspects.

Combine the approaches

Provided a rswag specs generated OpenAPI schema is more accurate, detailed and is an actual contract verification, but will be a lot of work to write:

How about documenting everything that rswag did not yet cover, with the generated approach, and fill in the better quality docs with rswag specs step by step?

[jippi]

Was this closed because it was resolved? 🤔

[casaper]

Was this closed because it was resolved? 🤔

Nah. I don't know how to close my issue without GitHub marking it as such.

I just did not want to leave any trash behind, when I decided not to contribute that RSwag OpenAPI docs thing.