Skip to content
GitLab

[Breaking change without fallback] [suggestion] [discussion] Split apis option as a semicolon-separated list

Closed Administrator requested to merge github/fork/shybovycha/fix/split-apis-parameter-as-a-list into master

Created by: shybovycha

Introduction

There is one quite nifty but undocumented option, apis, which could be set in system properties. It defines which API groups should be generated. Given the undocumented internal behavior of grouping all operations by tags, this gives an easy way to migrate existing projects to Open-API with minimal changes by automatically generating API definitions and then generating API interfaces with operations automatically grouped according to the existing endpoints.

Hence I am creating a few PRs (#4937, #4938, #4939) addressing this hidden gem of openapi-generator.

This change

Since apis is a (comma-separated) list itself and the additionalProperties option is also a (comma-separated) list, it is impossible to have a comma-separated list inside a comma-separated list with the existing parsing.

This PR introduces a behavioral change by treating the apisToGenerate list as semicolon-separated list. This way it is possible to pass it inside the list (such as additionalProperties).

Other two possible work-arounds I see are:

  1. introduce a x-generate-apis property and make it a normal comma-separated list; this will, however, require a bit of rework of the core logic by altering between apis and x-generate-apis values to populate the apisToGenerate variable in DefaultGenerator#generateApis, like in #4945 (since it is a private method - this can't be easily overriden for JavaJAXRSSpecServerCodegen only)
  2. there is one documented but weirdly used option, generateApis, which only stores the string representation of a boolean value in configuration (either in POM file or in CLI options), but later is transformed to either an empty string (representing the true) or null (representing false), see this. This could be replaced with a list of APIs to generate, essentially following option 1, just for a different config option

Happy to hear your thoughts on this.

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.