Skip to content
GitLab

[core] Normalizing vendor extension naming

Merged Jim Schubert requested to merge github/fork/jimschubert/normalizing-vendor-extensions into master

According to OAS 2.0 and OAS 3.0 Specifications:

Allows extensions to the OpenAPI Schema. The field name MUST begin with x-, for example, x-internal-id. The value can be null, a primitive, an array or an object. Can have any valid JSON format value.

This commit attempts to define a clear identifier design format of maintaining lower-kebab casing and following the x- prefix defined by OAI Specification.

Following a convention that matches that used by others (see autorest), we will remove any confusion about naming strategies for template authors and customizers. Following the lower-kebab convention will allow us to convert from camelCase and missing prefixes to the desired format. For example, these conversions are simple to make for template consistency:

  • customValue => x-custom-value
  • x-customValue => x-custom-value
  • x-custom-value => x-custom-value

This convention also allows us to define a single standard for use across all generators. This means no occurrence of x-operationId in one generator and x-operation-id in another.

Included in this PR is a logger which will log a warning message only once. This could be used for ModelUtils and UrlUtils to reduce stdout/stderr noise. The LoggerWrapper implementation is supported by an in-memory (caffeine) cache. I've added support for the following system properties so consumers with more advanced use cases can tweak/disable the caching OnceLogger:

  • org.openapitools.codegen.utils.oncelogger.enabled: set to false to disable the caching OnceLogger. Set to true to enable (the default).
  • org.openapitools.codegen.utils.oncelogger.cachesize: modify the cache size from the default of 200 messages (this is log message, not message count)
  • org.openapitools.codegen.utils.oncelogger.expiry: set the expiration time in millis to control how long messages remain in-memory. The default is 2000 (2 seconds), but could be made lower for high traffic consumers. For one-off use cases such as CLI, Maven Plugin, and Gradle Plugin, changing this property may not be useful.

NOTE This will require additional template work and removal of older extensions in the 5.0 branch. We'll need document the change(s) and upgrade path for the 5.0 release as well.

cc @OpenAPITools/generator-core-team @OpenAPITools/openapi-generator-collaborators

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.