[all] Adds strict spec option #2783
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
dkliban
reviewed
May 1, 2019
| @@ -214,6 +214,12 @@ | |||
| description = "Skips the default behavior of validating an input specification.") | |||
| private Boolean skipValidateSpec; | |||
|
|
|||
| @Option(name = {"--strict-spec"}, | |||
| title = "true/false strict behavior", | |||
| description = "'MUST' and 'SHALL' wording in OpenAPI spec is strictly adhered to, e.g. no fixes will be applied to documents which pass validation but don't follow the spec.", | |||
There was a problem hiding this comment.
s/, e.g. no/. When false, no/
dkliban
reviewed
May 1, 2019
| @@ -57,6 +57,7 @@ mvn clean compile | |||
| - `logToStderr` - write all log messages (not just errors) to STDOUT | |||
| - `enablePostProcessFile` - enable file post-processing hook | |||
| - `skipValidateSpec` - Whether or not to skip validating the input spec prior to generation. By default, invalid specifications will result in an error. | |||
| - `strictSpec` - Whether or not to treat an input document strictly against the spec. 'MUST' and 'SHALL' wording in OpenAPI spec is strictly adhered to, e.g. no fixes will be applied to documents which pass validation but don't follow the spec. | |||
There was a problem hiding this comment.
s/, e.g. no/. When false, no/
dkliban
approved these changes
May 1, 2019
|
Thanks for the review, it made me realize I had missed documenting the CLI option in a couple places. |
|
Forgot to assign from |
This was referenced Jun 3, 2019
6 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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
./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\.master,. Default:3.4.x,4.0.xmaster.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, 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/apiand the path isresource/{id}, this may result in a generated URL such ashttp://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:But, URLs with and without trailing
/are both valid.The field name for a paths object is defined as:
So, strictly following the spec here, it seems that when
server.url = /andpaths["/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 hostnameapi.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.