Skip to content

Regenerate OpenAPI documentation of REST API

Luke Duncalfe requested to merge ld-api-regenerate-openapi_v2 into master

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
image image

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

  1. 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 file openapi_v2.yaml.
  2. Now switch to master, and copy the contents of the doc/api/openapi/openapi_v2.yaml file and add it to the same repository. Name the file openapi.yaml.
  3. View each file in the repository (from master or this branch), they will present using the OpenAPI Viewer.
  4. Compare the views. For example, expand PUT /api/v4/users/{id}. Click Try out, change some values, and click Execute (it's okay if it fails due to CORS).
  5. Also Compare the curl the viewer generates (see below).
  6. Now compare how each viewer presents /api/v4/bulk_imports which uses the content-type 'application/x-www-form-urlencoded'. The viewer and also the curl generated should be identical to each other.
Edited by Luke Duncalfe

Merge request reports