Skip to content
GitLab
Projects Groups Snippets
  • /
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
    • Contribute to GitLab
  • Sign in / Register
  • O openapi-generator
  • Project information
    • Project information
    • Activity
    • Labels
    • Members
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
  • Issues 3,476
    • Issues 3,476
    • List
    • Boards
    • Service Desk
    • Milestones
  • Merge requests 402
    • Merge requests 402
  • CI/CD
    • CI/CD
    • Pipelines
    • Jobs
    • Schedules
  • Deployments
    • Deployments
    • Environments
    • Releases
  • Packages and registries
    • Packages and registries
    • Package Registry
    • Infrastructure Registry
  • Monitor
    • Monitor
    • Incidents
  • Analytics
    • Analytics
    • Value stream
    • CI/CD
    • Repository
  • Wiki
    • Wiki
  • Snippets
    • Snippets
  • Activity
  • Graph
  • Create a new issue
  • Jobs
  • Commits
  • Issue Boards
Collapse sidebar
  • OpenAPI Tools
  • openapi-generator
  • Merge requests
  • !4979

[core] Extracting recommendations to validation framework

  • Review changes

  • Download
  • Email patches
  • Plain diff
Merged Jim Schubert requested to merge github/fork/jimschubert/shared-validations into master Jan 12, 2020
  • Overview 0
  • Commits 6
  • Pipelines 0
  • Changes 20

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

Assignee
Assign to
Reviewers
Request review from
Time tracking
Source branch: github/fork/jimschubert/shared-validations