Autogenerate OpenApi using grape-swagger
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:
- Check out the
andysoiron/rake-task-to-generate-openapi-v2-documentation
branch. - Delete the
doc/api/openapi/openapi_v2.yaml
file. - Run
rake gitlab:openapi:generate
. - The file should be created again with the same content as before.
To check out the generated documentation
MR acceptance checklist
This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.
-
I have evaluated the MR acceptance checklist for this MR.
Edited by Andy Schoenen