Regenerate OpenAPI documentation of REST API
What does this MR do and why?
This updates the OpenAPI documentation to the version generated by
the latest grape-swagger
gem update
!152947 (merged).
The changes include describing the params in POST
and PATCH
requests more correctly
!152947 (comment 1907909527), observing the content-type described for the API endpoint.
MR acceptance checklist
Please evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.
Screenshots or screen recordings
Comparing how documentation for "/api/v4/jobs/{id}/trace"
appears:
Before | After |
---|---|
When you try executing a command in the Open API viewer with the YAML generated in this branch, it generates this curl
as an example of your request now, where params are part of the request body.
Example using curl
generated for PUT /api/v4/users/{id}
:
curl -X 'PUT' \
'http://gdk.test:3000/api/v4/users/1' \
-H 'accept: application/json' \
-H "PRIVATE-TOKEN: <TOKEN>" \
-H 'Content-Type: application/json' \
-d '{
"name": "root"
}'
compared to the old YAML where params are passed as query params (note, the Content-Type
):
curl -X 'PUT' \
'http://gdk.test:3000/api/v4/users/1' \
-H 'accept: application/json' \
-H "PRIVATE-TOKEN: <TOKEN>" \
-H 'Content-Type: multipart/form-data' \
-F 'name=root'
Execute the new curl
locally. The curl
should be valid. Note the API responds to both curl
versions, but the newer version is a more typical JSON request.
How to set up and validate locally
- Copy the contents of the
doc/api/openapi/openapi_v2.yaml
file from this branch and add it to a repository on your local GitLab. Name the fileopenapi_v2.yaml
. - Now switch to
master
, and copy the contents of thedoc/api/openapi/openapi_v2.yaml
file and add it to the same repository. Name the fileopenapi.yaml
. - View each file in the repository (from
master
or this branch), they will present using the OpenAPI Viewer. - Compare the views. For example, expand
PUT /api/v4/users/{id}
. ClickTry out
, change some values, and clickExecute
(it's okay if it fails due to CORS). - Also Compare the
curl
the viewer generates (see below). - Now compare how each viewer presents
/api/v4/bulk_imports
which uses the content-type'application/x-www-form-urlencoded'
. The viewer and also thecurl
generated should be identical to each other.