Many updates, you will need to update your configuration #586
deepmap-marcinr
announced in
Announcements
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
Many changes to code generation
We've had many big changes which affect code generation on the back burner, for fear of breaking code dependent on previous behavior, but this was holding back many fixes, so this release, in its default behavior, breaks generated code to be incompatible with existing code. However, we've been able to provide configuration options to disable this new behavior in all cases. So, with small changes to how
oapi-codegen
is invoked, you can continue to generate compatible code, however, you will not have these new changes, all of which fix bugs.Configuration and flag changes
First, we are moving from flag based configuration of the tool, to using a configuration file. The configuration file is directly loaded into the Options struct used by the
codegen
package. A number of the former flags are ignored, and the former configuration file will fail to load with default settings.To help you migrate your configuration options, we've provided several new flags:
--old-config-style
: When set, we will correctly parse all flags and configuration files in the previous way. When it becomes inconvenient to maintain this flag, we will remove it.--output-config
: When set,oapi-codegen
will output a new-style configuration file based from all flags and an existing configuration file. Combined with the previous flag, you can use the tool to update your configuration files.If previously you were running a command like:
You will now get an error:
By adding the
--old-config-style
, code will be generated:But, we're moving away from flags, so you can generate a config file like so:
And you will see this output:
You can save that to a config file, and use that to configure oapi-codegen in the future.
Schema merging for
allOf
has been rewrittenThe expanded petstore example contains an
allOf
schema which mergesNewPet
properties with an ID:In the past, we would generate this code:
With this release, we generate this:
In this new release, we merge the OpenAPI schemas before generating the Go object - which allows for modifiers like
required
to affect the type union. This makes the generated types closer to the intent of the OpenAPI specification.Since this is a breaking change, we've provided a configuration file option to select the old behavior:
$ref
prefers type aliasingIn prior releases, a
$ref
to another type would create a type declaration.Say that we have this spec fragment:
Prior releases would generate:
This release will generate:
We will create type definitions for anything we create that needs its own named type, like objects and enums, but everything else will be a type alias where this is possible. We did this for two major reasons. The first is that type redefinitions remove methods, like those of the
json.Unmarshaler
interface, which breaks JSON marshaling. The second reason is that all these types make working with the generated code annoying due to many type conversions.Since this is a breaking change, you can disable it:
The former
--alias-types
flag is now defunct, since it's effectively always on. it's no longer used.Enum value name collision resolution
In prior releases, two enums of different types but with the same values would result in a type collision. This release adds new code which performs global enum value collision detection, and it prefixes the typename to the enum values to resolve this collision. For example, consider this schema:
Previously, we would generate non-compiling code:
Now, we generate:
This conflict resolution will not do anything if there is no conflict, but when two types have conflicting typenames, then both will have their typename prefixed to the value types, so this change should not be breaking, because the affected code is already broken, and currently working code will not trigger the resolution.
However, if for some reason it does break existing specs, you can disable it:
What's Changed
x-go-name
for parameters var name by @emilekm in Use lower-casedx-go-name
for parameters var name #574SecurityProvider
documentation by @jamietanna in Apply syntax highlighting toSecurityProvider
documentation #576New Contributors
SecurityProvider
documentation #576Full Changelog: v1.10.1...v1.11.0
This discussion was created from the release Many updates, you will need to update your configuration.
Beta Was this translation helpful? Give feedback.
All reactions