Page MenuHomePhabricator

Make services swagger specs standard compliant
Open, MediumPublic

Description

It's been decided that we need to drop support for optional path parameters in our swagger specifications to become swagger spec compliant. That will allow us to drop Wikimedia swagger-ui fork and switch to upstream UI. Additionally, we would be able to use new features of Swagger 3.

In case the service does not optional path parameters, the task is only about using new features of Swagger 3. In case optional parameters are used, each path should be split into several declarations with only required parameters. So,

/{foo}{/bar}{/baz}

should become 3 paths:

/{foo}
/{foo}/{bar}
/{foo}/{bar}/{baz}

In order to minimize copy-pasting, it's would be preferred to use swagger 3 components feature or YAML references.

The resulting spec has to pass swagger spec validation.

Event Timeline

jijiki triaged this task as Medium priority.Mar 19 2019, 6:19 PM

In order to minimize copy-pasting, it's would be preferred to use swagger 3 components feature or YAML references.

@Pchelolo Does that mean that we need to upgrade spec.yaml to be compliant with OpenAPI 3? The components feature are not available for swagger v2.0 specs. From https://swagger.io/docs/specification/components/ :

This page applies to OpenAPI 3 – the latest version of the OpenAPI Specification.

@MSantos I think we do want to go up to OpenAPI 3; that's actually in progress right now for RESTBase and friends (T218218).

I do not really understand what needs to be done within mathoid. Mathoid has two dependencies

"swagger-router": "^0.7.4",
"swagger-ui-dist": "^3.25.0" (optional, because it was incompatible at some point in time and has not been working for me since then)

Since IMHO nobody ever uses the swagger-ui in its current form, we can just drop these and reintroduce standard swagger-ui components if needed. When I tried that I realized that https://github.com/wikimedia/swagger-router/blob/797375ac0e80ba913a08787b17c72ef303042a15/lib/uri.js is used quite a lot in the tests. If this is also the case in other libraries, maybe it would be worth the effort to describe the migration path for URI in this ticket, so that not every library goes its own route.

I do not really understand what needs to be done within mathoid. Mathoid has two dependencies

"swagger-router": "^0.7.4",
"swagger-ui-dist": "^3.25.0" (optional, because it was incompatible at some point in time and has not been working for me since then)

Since IMHO nobody ever uses the swagger-ui in its current form, we can just drop these and reintroduce standard swagger-ui components if needed. When I tried that I realized that https://github.com/wikimedia/swagger-router/blob/797375ac0e80ba913a08787b17c72ef303042a15/lib/uri.js is used quite a lot in the tests. If this is also the case in other libraries, maybe it would be worth the effort to describe the migration path for URI in this ticket, so that not every library goes its own route.

Here is how we did for mobileapps https://gerrit.wikimedia.org/r/c/mediawiki/services/mobileapps/+/514414/1

Change 727138 had a related patch set uploaded (by Santhosh; author: Santhosh):

[mediawiki/services/cxserver@master] Update API Spec to OpenAPI 3.0

https://gerrit.wikimedia.org/r/727138

Change 727138 merged by jenkins-bot:

[mediawiki/services/cxserver@master] Update API Spec to OpenAPI 3.0

https://gerrit.wikimedia.org/r/727138

Change 734288 had a related patch set uploaded (by KartikMistry; author: KartikMistry):

[operations/deployment-charts@master] Update cxserver to 2021-10-25-123807-production

https://gerrit.wikimedia.org/r/734288

Change 734288 merged by jenkins-bot:

[operations/deployment-charts@master] Update cxserver to 2021-10-25-123807-production

https://gerrit.wikimedia.org/r/734288