This is work to extract recommendation logic out of the CLI validate command into a shared evaluation instance which can be used elsewhere (such as Gradle, or the Online tool).
For now, these validations are in addition to those provided by swagger-parser and are only the following recommendations:
- Apache/Nginx warning that header values with underscore are dropped by default
- Unused models/schemas
- Use of properties with oneOf, which is ambiguous in OpenAPI Specification
- GET/HEAD operations defined with body considered an anti-pattern
I've allowed for disabling recommendations via System properties, since this is something that has been requested a few times by users. System properties in this commit include:
- openapi.generator.rule.recommendations=false
- Allows for disabling recommendations completely. This wouldn't include all warnings and errors, only those we deem to be suggestions
- openapi.generator.rule.apache-nginx-underscore=false
- Allows for disabling the Apache/Nginx warning when header names have underscore
- This is a legacy CGI configuration, and doesn't affect all web servers
- openapi.generator.rule.oneof-properties-ambiguity=false
- We support this functionality, but the specification may not intend for it
- This is more to reduce noise
- openapi.generator.rule.unused-schemas=false
- We will warn when a schema is not referenced outside of Components, which users have requested to be able to turn off
- openapi.generator.rule.anti-patterns.uri-unexpected-body=false
This moves validations as suggested in #4412, and prepares for sharing it with other tools in our project.
Example output:
openapi-generator validate -i samples/server/petstore/python-aiohttp/openapi_server/openapi/openapi.yaml --recommend
Validating spec (/Users/jim/projects/openapi-generator/samples/server/petstore/python-aiohttp/openapi_server/openapi/openapi.yaml)
Warnings:
- Apache and Nginx webservers may fail due to legacy CGI constraints enabled by default in
which header keys with underscore are disallowed. See
https://stackoverflow.com/a/22856867/151445.
- Schemas defining properties and oneOf are not clearly defined in the OpenAPI
Specification. While our tooling supports this, it may cause issues with other tools.
[info] Spec has 2 recommendation(s).
PR checklist
-
Read the contribution guidelines. -
If contributing template-only or documentation-only changes which will change sample output, build the project before. -
Run the shell script(s) under ./bin/
(or Windows batch scripts under.\bin\windows
) to update Petstore samples related to your fix. This is important, as CI jobs will verify all generator outputs of your HEAD commit, and these must match the expectations made by your contribution. You only need to run./bin/{LANG}-petstore.sh
,./bin/openapi3/{LANG}-petstore.sh
if updating the code or mustache templates for a language ({LANG}
) (e.g. php, ruby, python, etc). -
File the PR against the correct branch: master
,4.3.x
,5.0.x
. Default:master
. -
Copy the technical committee to review the pull request if your PR is targeting a particular programming language.
cc @ybelenko @OpenAPITools/generator-core-team