Page MenuHomePhabricator

Make services swagger specs standard compliant
Open, NormalPublic

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.

  • service-template - should be updated to depend on the upstream Swagger UI version.
  • citoid
  • cxserver
  • eventstreams
  • graphoid
  • mathoid
  • mobileapps
  • proton
  • recommendation-api

Event Timeline

Pchelolo created this task.Mar 13 2019, 2:29 PM
jijiki triaged this task as Normal priority.Mar 19 2019, 6:19 PM
Mvolz moved this task from Backlog to Service on the Citoid board.Apr 1 2019, 3:52 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).

Pchelolo updated the task description. (Show Details)Jun 5 2019, 8:22 AM
fsero moved this task from Backlog to Incoming on the serviceops board.Jun 20 2019, 2:24 PM
Joe edited projects, added serviceops-radar; removed serviceops.Jun 21 2019, 8:49 AM
Joe moved this task from Backlog to Watched on the serviceops-radar board.Jun 21 2019, 8:52 AM