Change Details

In T217747 it was discovered that in WMF REST services we use swagger spec's that violate the specification. Specifically, while the swagger specification for either version 2.x or 3.x does not allow to have optional path patameters, our specs used a devised syntax to denote it, a syntax that violates the original specification Per T217747#5007514 ``` version 2.0 of swagger spec does not allow optional path paramerts. WMF has this kind of definition(not limited to cxserver). See comment by @GWicke at https://github.com/OAI/OpenAPI-Specification/issues/93#issuecomment-74362417 ``` In the above comments it is clear an effort was made to add support for `RFC 6570 URI templates` to the specification, an effort that has effectively failed. 3 years after that effort, and despite it being an often asked feature per https://github.com/OAI/OpenAPI-Specification/issues/574 the addition of RFC 6570 URI template is set as `deferred`. My personal estimation of the chance of this being added to the spec in a later version is, that it's minimal. OpenAPI/Swagger 3.0.2, a very recently released version (and the current one), still says very clearly [1] ``` required boolean Determines whether this parameter is mandatory. If the parameter location is "path", this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be included and its default value is false. ``` So, are in the precarious position of effectively using an in-house version of the specification that: * has the same name AND versioning as the original, causing confusion * is largely compatible with the original, but in reality the violating part is used extensively in WMF (it's at least used at https://gerrit.wikimedia.org/r/494703) * admittedly noone else uses (that we know of?) * no tooling exists around it to validate the correctness of it * the standard tooling fails For a demonstration of the last bullet point, just using https://editor.swagger.io/ and feeding it one of our spec's (e.g. https://raw.githubusercontent.com/wikimedia/mediawiki-services-cxserver/master/spec.yaml) will make the issue appear. Using other tooling like https://github.com/pyopenapi/pyswagger or https://pypi.org/project/swagger-parser/ also demonstrates the issue. Up to now our own tooling seems to treat our spec.yaml files as yaml and does not validate the correctness of the specification so no real issues have appeared yet, but with the number of services bound to increase, this has higher chances of becoming an issue. Maybe it's about time we re-evaluate our divergence from the spec and perhaps conform to the spec? [1] https://swagger.io/specification/#parameterObject

In T217747 it was discovered that in WMF REST services we use swagger spec's that violate the specification. Specifically, while the swagger specification for either version 2.x or 3.x does not allow to have optional path patameters, our specs used a devised syntax to denote it, a syntax that violates the original specification Per T217747#5007514 ``` version 2.0 of swagger spec does not allow optional path paramerts. WMF has this kind of definition(not limited to cxserver). See comment by @GWicke at https://github.com/OAI/OpenAPI-Specification/issues/93#issuecomment-74362417 ``` In the above comments it is clear an effort was made to add support for `RFC 6570 URI templates` to the specification, an effort that has effectively failed. 3 years after that effort, and despite it being an often asked feature per https://github.com/OAI/OpenAPI-Specification/issues/574 the addition of RFC 6570 URI template is set as `deferred`. My personal estimation of the chance of this being added to the spec in a later version is, that it's minimal. OpenAPI/Swagger 3.0.2, a very recently released version (and the current one), still says very clearly [1] ``` required boolean Determines whether this parameter is mandatory. If the parameter location is "path", this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be included and its default value is false. ``` So, are in the precarious position of effectively using an in-house version of the specification that: * has the same name AND versioning as the original, causing confusion * is largely compatible with the original, but in reality the violating part is used extensively in WMF (it's at least used at https://gerrit.wikimedia.org/r/494703) * admittedly noone else uses (that we know of?) * no tooling exists around it to validate the correctness of it * the standard tooling fails For a demonstration of the last bullet point, just using https://editor.swagger.io/ and feeding it one of our spec's (e.g. https://raw.githubusercontent.com/wikimedia/mediawiki-services-cxserver/master/spec.yaml) will make the issue appear. Using other tooling like https://github.com/pyopenapi/pyswagger or https://pypi.org/project/swagger-parser/ also demonstrates the issue. Up to now our own tooling seems to treat our spec.yaml files as yaml and does not validate the correctness of the specification so no real issues have appeared yet, but with the number of services bound to increase, this has higher chances of becoming an issue. Maybe it's about time we re-evaluate our divergence from the spec and perhaps conform to the spec? Conforming to the spec would mean that we change our spec files to become more verbose and list all possible permutations that result from the optional nature of a path. e.g. `/required/optional1/optional2/` would mean that instead of a spec `/required{/optional1}{/optional2}` we would have to list ``` /required /required/optional1 /required/optional2 /required/optional1/optional2 ``` Adding that every path stanza can be easily 100 lines of yaml in order to describe methods, responses and monitoring, the benefits of the templating support, if it existed are obvious, but it does not exist. [1] https://swagger.io/specification/#parameterObject

In T217747 it was discovered that in WMF REST services we use swagger spec's that violate the specification. Specifically, while the swagger specification for either version 2.x or 3.x does not allow to have optional path patameters, our specs used a devised syntax to denote it, a syntax that violates the original specification Per T217747#5007514 ``` version 2.0 of swagger spec does not allow optional path paramerts. WMF has this kind of definition(not limited to cxserver). See comment by @GWicke at https://github.com/OAI/OpenAPI-Specification/issues/93#issuecomment-74362417 ``` In the above comments it is clear an effort was made to add support for `RFC 6570 URI templates` to the specification, an effort that has effectively failed. 3 years after that effort, and despite it being an often asked feature per https://github.com/OAI/OpenAPI-Specification/issues/574 the addition of RFC 6570 URI template is set as `deferred`. My personal estimation of the chance of this being added to the spec in a later version is, that it's minimal. OpenAPI/Swagger 3.0.2, a very recently released version (and the current one), still says very clearly [1] ``` required boolean Determines whether this parameter is mandatory. If the parameter location is "path", this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be included and its default value is false. ``` So, are in the precarious position of effectively using an in-house version of the specification that: * has the same name AND versioning as the original, causing confusion * is largely compatible with the original, but in reality the violating part is used extensively in WMF (it's at least used at https://gerrit.wikimedia.org/r/494703) * admittedly noone else uses (that we know of?) * no tooling exists around it to validate the correctness of it * the standard tooling fails For a demonstration of the last bullet point, just using https://editor.swagger.io/ and feeding it one of our spec's (e.g. https://raw.githubusercontent.com/wikimedia/mediawiki-services-cxserver/master/spec.yaml) will make the issue appear. Using other tooling like https://github.com/pyopenapi/pyswagger or https://pypi.org/project/swagger-parser/ also demonstrates the issue. Up to now our own tooling seems to treat our spec.yaml files as yaml and does not validate the correctness of the specification so no real issues have appeared yet, but with the number of services bound to increase, this has higher chances of becoming an issue. Maybe it's about time we re-evaluate our divergence from the spec and perhaps conform to the spec? Conforming to the spec would mean that we change our spec files to become more verbose and list all possible permutations that result from the optional nature of a path. e.g. `/required/optional1/optional2/` would mean that instead of a spec `/required{/optional1}{/optional2}` we would have to list ``` /required /required/optional1 /required/optional2 /required/optional1/optional2 ``` Adding that every path stanza can be easily 100 lines of yaml in order to describe methods, responses and monitoring, the benefits of the templating support, if it existed are obvious, but it does not exist. [1] https://swagger.io/specification/#parameterObject