Page MenuHomePhabricator

Make RESTBase spec standard compliant and switch to OpenAPI 3.0
Open, Stalled, NormalPublic2 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

Pchelolo created this task.Mar 13 2019, 2:34 PM

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

Pchelolo reassigned this task from holger.knust to Clarakosi.EditedMar 25 2019, 4:06 PM
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

Pchelolo updated the task description. (Show Details)Apr 2 2019, 4:40 PM

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

mobrovac triaged this task as Normal priority.
mobrovac edited projects, added Services (doing); removed Services (later).
mobrovac updated the task description. (Show Details)Apr 3 2019, 3:08 PM

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.

mobrovac updated the task description. (Show Details)Apr 9 2019, 7:22 PM
Pchelolo updated the task description. (Show Details)Apr 9 2019, 7:51 PM

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.

This work is stalled until other RESTBase patches are merged.