Skip to content

Autogenerate OpenApi using grape-swagger

Andy Schoenen requested to merge andysoiron/rake-task-to-generate-openapi-v2-documentation into master

What does this MR do and why?

This adds a simple rake task that generates an OpenAPI V2 document from the Grape API endpoint descriptions. It is a very small fist iteration that allows us to quickly generate an OpenAPI document to run API FUZZ testing on. See the related discussion here: #372422 (comment 1088861657)

It adds:

  • The grape-swagger gem for development
  • The grape-swagger-entity gem for development
  • Annotations for the /api/v4/version endpoint
  • The openapi_v2.yaml file describing the version endpoint as an example

In later iterations, we can add

  • A test that generates that makes sure openapi_v2.yaml is up-to-date
  • Documentation for how to use the task and how to contribute to openapi_v2.yaml
  • Annotations for all other endpoints

Related issue: https://gitlab.com/gitlab-org/gitlab/-/issues/375259

How to set up and validate locally

To check out the yaml file generation:

  1. Check out the andysoiron/rake-task-to-generate-openapi-v2-documentation branch.
  2. Delete the doc/api/openapi/openapi_v2.yaml file.
  3. Run rake gitlab:openapi:generate.
  4. The file should be created again with the same content as before.

To check out the generated documentation

  1. Go to https://gitlab.com/gitlab-org/gitlab/-/blob/2665b93dd8e14b3ebbc799aa8047303bd1283b14/doc/api/openapi/openapi_v2.yaml

MR acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Andy Schoenen

Merge request reports