Introduces an option to allow user customization of strict specification behaviors. For instance, OpenAPI 3.x requires a path object name to be prefixed with '/' so we append any missing '/', but this may not be desirable to some users or generators. In this commit, this fix specifically is the only modification affected.
PR checklist
-
Read the contribution guidelines. -
Ran the shell script under ./bin/to update Petstore sample so that CIs can verify the change. (For instance, only need to run./bin/{LANG}-petstore.sh,./bin/openapi3/{LANG}-petstore.shif updating the {LANG} (e.g. php, ruby, python, etc) code generator or {LANG} client's mustache templates). Windows batch files can be found in.\bin\windows\. -
Filed the PR against the correct branch: master,. Default:3.4.x,4.0.xmaster. -
Copied the technical committee to review the pull request if your PR is targeting a particular programming language.
Description of the PR
Adds an option which allows users to disable any strict specification behaviors applied during generation. For example, #1034 introduces a modification which prefixes all paths missing a beginning slash to better fit "MUST" definitions in the OpenAPI Specification 3.x. Ideally, this behavior would be rolled up into the parser (i.e. if we've validated via the parser, we shouldn't need to fix the spec document).
Such a switch is necessary because, as discussed in #2702 (closed), users may not want the input document to be modified to match strict behaviors against the specification.
Use of this option to disable strict behaviors, however, does mean that one or more generators may not work as expected. For example, if the url part of a document is: http://localhost/api and the path is resource/{id}, this may result in a generated URL such as http://localhost/apiresource/{id}.
Note that there seems to be a discrepancy or error in the OpenAPI 3.0.x specification. A server url object default is a server with relative url /. The url requirement is defined as:
REQUIRED. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in {brackets}.
But, URLs with and without trailing / are both valid.
The field name for a paths object is defined as:
A relative path to an individual endpoint. The field name MUST begin with a forward slash (/). The path is appended (no relative URL resolution) to the expanded URL from the Server Object's url field in order to construct the full URL. Path templating is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it's up to the tooling to decide which one to use.
So, strictly following the spec here, it seems that when server.url = / and paths["/api"] exist, the desired outcome (no relative URL resolution, appending path to URL) is //api, which obviously isn't correct as this means the protocol-relative hostname api.
This PR does not attempt to resolve any concerns with the above scenario; it is only provided as an example of why we follow strict behaviors by default and need to sometimes modify what a user provides (even when it successfully validates against the spec).
/cc @OpenAPITools/generator-core-team
TODO
Once merged, the option will need to be applied to the gradle plugin. It seems to always resolve against maven with greater precedence over mavenLocal, and I'm hesitant to shift repository settings around and introduce any issues with the build pipeline.