In THREESCALE-3927 (PR #3103) 3scale API docs were upgraded from the old Swagger v1 to the new OpenAPI v3.

There are some things that can be improved, that were not part of that PR. I am listing them here, and they would need to be evaluated, and if we decide to go ahead with these improvements, they can be extracted to a separate subtask.

"Regressions" (small features that were "lost" after the upgrade)

1. Autocomplete for the request body

Autocomplete based on the "account data" (account, application, application plan IDs for Acc Mgmt API; metrics, service IDs, user keys for Service Mgmt API, etc.) only works for the parameters in path and query parameters, but not for those that are in the request body (PUT, POST methods). This used to work in Swagger v1. In the new specification the definition of the body is different from the parameters, so autocomplete should be handled separately.

2. "Send empty value" checkbox

In the old Swagger, when the field was left with an empty value it was included in the request. The new Swagger UI has an option of either including the param with an empty value, or not including the param at all, based on the value of the "Send empty value" checkbox, which is enabled by default. In order to have the same default behavior as before, the checkbox needs to be disabled. This can be achieved by adding a custom plugin to Swagger UI (feature request for Swagger UI and an exampe of the plugin can be found in swagger-ui issue 6505).

Specification and UX improvements

3. Add definitions for request and responses

Currently, there is only a small number of requests that have schema definitions. Ideally, all requests and responses should have definitions to facilitate writing clients for the API.

4. xml vs json selector

Most of the APIs have both XML and JSON variants. It could be nice if we had a selector that would allow choosing the content type of the response. Just for reference, there is a number of RFEs that aim to make JSON the new default for all endpoints, and possibly deprecate XML (see THREESCALE-5691 and THREESCALE-8327).

Refactoring (not visible to users)

5. Remove duplication in the spec

Currently, some pieces of specification are duplicated (endpoints with the same set of parameters). We could improve the specification by reducing such duplication. It would probably be solved mostly if we implement number 3.
Also, OpenAPI v3 allows defining parameters on path level rather than operation level. Maybe this could also be done, for example for the access token that is required for all operations in Acc Mgmt API.

6. Refactor the view template, switching from ERB to slim

7. Change the format of the specification files from JSON to YAML

Currently, the specifications are modified manually (there is an RFE to generate specs with some tooling - THREESCALE-5242 )

Editing YAML is nicer and more user-friendly (and can be done nicely in Swagger Editor, for example), so it could be interesting to have the specs in YAML instead of JSON in our source code.

8. operationId could be added to each operation in the specification. Currently, there is no functionality that would use operationId, but it can be useful for code generation etc.

9. Remove the "on-premises" variant of the Service Management API spec.

There are currently two different files for the Svc Mgmt API - one for on-premises, and another one for SaaS. The only difference between them is that SaaS one includes the "log" parameter. This change could potentially be handled programmatically, without having the rest of the spec duplicated (which means that any change would need to be done twice).