Improve and expand existing OpenAPI 2 / Swagger Documentation for REST API v4
Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.
Proposal
Customers are interested in leveraging OpenAPI to access our APIs. This is explores expanding on our current OpenAPI support in OpenAPI 2.0 / Swagger.
There are two main ways to do this - either using the grape-swagger gem (https://github.com/ruby-grape/grape-swagger) to generate OpenAPI 2.0 compliant docs from annotations (we do not use this gem at the moment), or to manually create such docs for each endpoint (see doc/api/openapi/openapi.yaml in our repo - this is fairly skeletal at the moment). in summary, the fastest way is to add new entries to doc/api/openapi/openapi.yaml, the best way is to start using grape-swagger, but given the under-annotated state of our endpoints, I'm not sure that is going to be straightforward.
If we were to consider support for OpenAPI 3.0 or 3.1, this would require a separate issue as more discovery would likely be required.
The main difference in 3.0 is the links property (which we don't support in general). There is also some work on OpenAPI 3.0 in Grape (see https://github.com/ruby-grape/grape-swagger/pull/744). However, the support for this seems a bit iffy.