Skip to content

Latest commit

 

History

History
97 lines (58 loc) · 4.7 KB

migration-guide.adoc

File metadata and controls

97 lines (58 loc) · 4.7 KB
Raw

Migration guide between OpenAPI-Generator versions

This page summaries the important changes between major and minor version of OpenAPI-Generator. It does not contain a detailed list of changes, for that refer to each individual release notes.

This page is written to help migration by indicating the most impacting changes. Do not hesitate to contribute additional notes if you discover something during your migration and think that the information might help other users.

Another approach to find breaking changes is to look at issue and pull requests with following labels:

From 3.x to 4.0.0

Version 4.0.0 is a major release, which contains some breaking changes without fallback.

The -l (--lang) option has been deleted

The option is replaced with -g (--generator-name).

  • -g allows the same values as -l

  • See list command for the list of generator name

Access OpenAPI instance as member and not as parameter

If you are creating or extending a generator (programmatically), you might have use one of the following parameters: OpenAPI openAPI or Map<String, Schema> allDefinitions or Map<String, Schema> allSchemas. Example methods:

  • CodegenConfig#fromOperation(String, String, Operation, Map<String, Schema>, OpenAPI)

  • CodegenConfig#fromModel(String, Schema, Map<String, Schema>)

  • DefaultCodegen#fromResponse(OpenAPI, String, ApiResponse)

  • DefaultCodegen#DefaultCodegen.fromRequestBody(RequestBody, Map<String, Schema>, Set<String>, String)

  • DefaultCodegen#createDiscriminator(String, Schema, Map<String, Schema>)

  • …​

The parameters (openAPI, allDefinitions, allSchemas …​) are now removed from the methods.

To access the current OpenAPI instance, if you are extending DefaultCodegen you can use the protected openAPI member.

If you are creating your own generator by implementing CodegenConfig, then the setter CodegenConfig.setOpenAPI(OpenAPI) will be called. You can keep a reference on the OpenAPI instance.

From 3.1.x to 3.2.0

Version 3.2.0 is a minor version of OpenAPI-Generator, in comparison to 3.1.x it contains some breaking changes, but with the possibility to fallback to the old behavior. The default value of some options might change. Projects relying on generated code might need to be adapted.

Validate spec on generation by default

The default is to validate the spec during generation. If the spec has errors, they will appear as errors or warnings to the user. This prevents generation of the project.

If you want to switch back to the 3.1.x behavior you can use:

  • Set the validateSpec option to false if you are using the Maven or Gradle plugin

  • Use the command line option --skip-validate-spec if you are using the CLI

Model (all languages)

In CodegenModel and in CodegenOperation we use now our own class org.openapitools.codegen.CodegenDiscriminator instead of io.swagger.v3.oas.models.media.Discriminator.

For the templates, this is not an API change, because the same values are available.

If you have your own Codegen class (to support your own generator for example) then you might get some compile error due to the change.

Java

Schema with enum values are mapped to java enum in the generated code. In previous version, when an unknown value was deserialized, the value was set to null.

With 3.2.0 a new option is introduced: useNullForUnknownEnumValue.

  • When set to false (default value), an Exception (IllegalArgumentException) is thrown when the value not available in the enum.

  • When set to true, unknown values are mapped to null as it was the case in previous versions.

From 3.0.x to 3.1.0

Version 3.1.0 is the first minor version of OpenAPI-Generator, in comparison to 3.0.3 it contains some breaking changes, but with the possibility to fallback to the old behavior. The default value of some options might change. Projects relying on generated code might need to be adapted.

Java

A new option is introduced with #432 to specify the prefix of boolean getters: booleanGetterPrefix. Possible values:

  • is: the value used in 3.0.x.

  • get: the new default value.

If you use the default value you will see your generated code changing from isActive() to getActive().

Migrating from Swagger-Codegen

Please read the specific migration guide: From Swagger-Codegen to OpenAPI-Generator