Page MenuHomePhabricator

Make RESTBase spec standard compliant and switch to OpenAPI 3.0
Closed, ResolvedPublic2 Estimated Story Points

Description

RESTBase swagger spec has to be made spec-compliant and switched to OpenAPI 3.0.

This would require several steps:

  • Replace all the paths that use optional parameters with a set of paths with required parameters, but still be swagger 2.0 compliant.
  • Remove support for optional path parameters from swagger-router and from the spec parser, add support or swagger 3.0 features.
  • Replace all the optional paths in the /sys hierarchy
  • Start using swagger 3.0 features.

Event Timeline

Verified that we can work with swagger-ui 3+ once we make the spec standard-compliant. Let's begin with modifying the specs.

Pchelolo added a subscriber: holger.knust.

For step 2 we need to switch hyperswitch to upstream swagger.

Nowadays the swagger-ui bundle is in a different package: swagger-ui-dist. We need to make use of it instead of the fork we've been using.

The package is exposing index.html with some defaults same way as old swagger-ui package did, and we've used to modify that index.html via regexes.
I do not particularly like that solution, so we need to modify it and create a helper to generate an index.html from the config. We could also upstream the helper afterwards, there's been some talk about that.

Alternatively, we should propose to upstream a helper function to generate proper index.html on the fly.

Mentioned in SAL (#wikimedia-operations) [2019-04-02T16:39:36Z] <ppchelko@deploy1001> Started deploy [restbase/deploy@6026ad1]: Switch to swagger 3 T218218

Mentioned in SAL (#wikimedia-operations) [2019-04-02T16:44:27Z] <ppchelko@deploy1001> Finished deploy [restbase/deploy@6026ad1]: Switch to swagger 3 T218218 (duration: 04m 52s)

Mentioned in SAL (#wikimedia-operations) [2019-04-02T17:27:36Z] <ppchelko@deploy1001> Started deploy [restbase/deploy@3dcf328] (dev-cluster): Upgrade swagger to v3, attempt 2, T218218

Mentioned in SAL (#wikimedia-operations) [2019-04-02T17:30:38Z] <ppchelko@deploy1001> Finished deploy [restbase/deploy@3dcf328] (dev-cluster): Upgrade swagger to v3, attempt 2, T218218 (duration: 03m 02s)

Mentioned in SAL (#wikimedia-operations) [2019-04-02T17:30:49Z] <ppchelko@deploy1001> Started deploy [restbase/deploy@3dcf328]: Upgrade swagger to v3, attempt 2, T218218

Mentioned in SAL (#wikimedia-operations) [2019-04-02T17:51:36Z] <ppchelko@deploy1001> Finished deploy [restbase/deploy@3dcf328]: Upgrade swagger to v3, attempt 2, T218218 (duration: 20m 47s)

The new UI has been deployed. Next step here - explore the new features in openAPI 3.0, see what we can start using, converting the specs into 3.0.

I believe some code support in hyperswitch will be required for using the new features, but it should be minimal

One other thing left to do here: replace optional parameters in the /sys hierarchy specs.

One other thing left to do here: replace optional parameters in the /sys hierarchy specs.

PR #1111 changed this. Final step: turn the public-facing spec(s) into OpenApi v3.0 specs.

Change 503028 had a related patch set uploaded (by Alexandros Kosiaris; owner: Alexandros Kosiaris):
[mediawiki/services/mathoid@master] Update spec to OpenAPI 3.0.1

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

Change 503028 merged by Mobrovac:
[mediawiki/services/mathoid@master] Update spec to OpenAPI 3.0.1

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

WDoranWMF set the point value for this task to 2.Apr 15 2019, 3:14 PM

Change 507489 had a related patch set uploaded (by Clarakosi; owner: Clarakosi):
[operations/software/service-checker@master] Add support for OpenAPI 3.0

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

Change 507489 merged by Giuseppe Lavagetto:
[operations/software/service-checker@master] Add support for OpenAPI 3.0

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

CCicalese_WMF changed the task status from Open to Stalled.May 13 2019, 2:57 PM
CCicalese_WMF reassigned this task from Clarakosi to Pchelolo.

This work is stalled until other RESTBase patches are merged.

mobrovac changed the task status from Stalled to Open.May 29 2019, 8:14 AM
mobrovac updated the task description. (Show Details)

Last step: deployment

Mentioned in SAL (#wikimedia-operations) [2019-05-30T07:21:10Z] <mobrovac@deploy1001> Started deploy [restbase/deploy@92591a7]: Switch to OpenAPI v3 and drop page/html/title/revision/tid - T218218 T215956

Mentioned in SAL (#wikimedia-operations) [2019-05-30T07:40:37Z] <mobrovac@deploy1001> Finished deploy [restbase/deploy@92591a7]: Switch to OpenAPI v3 and drop page/html/title/revision/tid - T218218 T215956 (duration: 19m 28s)