Fix an issue with command line parsing

• The -o flag specifying the output filename was being ignore in very simple invocations of oapi-codegen without a configuration file. This is fallout from trying to be compatible with old and new style configs.

Many bug fixes

Major changes to functionality

• In the last release, we changed the configuration file format to a new syntax, and added flags to read the old version, but it turns out that this default-on change broke a lot of automation, sorry about that. In this release, we've done our best to auto-detect the configuration version, so both styles of config options should work. The explicit version selection flags have not been removed.
• Gorilla router (#594)
• "strict" server generation, meaning one which is much more pedantic about input and output types, which allows for making API clients and servers that look more like Go functions than HTTP handlers (#499)
• Fields can be marked with x-json-ignore to omit in JSON serialization (#390)
• Many fixes to unions for oneOf and anyOf handling, thank you committers.
• Enums can be prefixed with their typename in all cases, versus only on collisions previously. This is a configurable option (#662)
• The Client interface in generated code was named awfully generically. You can now override the name (#788)
• Generate code can be optionally formatted using more initialisms. It's default-off to not break existing code (#749)
• Gin code can be configured with a custom error handler, versus generating error responses inline. Default behavior is the same as before (#587)
• Gin middleware evaluation order can be reversed to be consistent with common Gin usage, it's default-off to not break previous behavior. ( #787)

Everything that has changed

This is a very large release with many bug fixes. Thanks to all contributors.

• use BindStyledParameterWithLocation with path params by @jcalvarado1965 in #564
• Correct reference to flag for backwards compatible configuration by @jamietanna in #594
• Add support for Gorilla generation by @jamietanna in #585
• chi : Change the signature of the MiddlewareFunc for compatibilities. by @uhey22e in #578
• docs: replace go get with go install by @mycrEEpy in #588
• oneOf/anyOf support (including discriminator) by @Warboss-rus in #471
• refactor(pkg/codegen): add goCode to error by @sashamelentyev in #599
• Add missing space between words by @jamietanna in #589
• [#211] Generate OpenAPI dictionaries without fixed keys as maps by @natsukagami in #424
• Fix UUID query param binding by @karl-dau in #623
• Strict server generation by @Warboss-rus in #499
• comment fixed in gin example code by @nsaltun in #646
• Fix small typo in comment by @LelouBil in #641
• Support param styling for UUIDs by @rliebz in #643
• Allow binding types as parameters through String() methods by @jamietanna in #638
• fix: support encoding.TextMarshaler in StyleParamWithLocation by @mazitovt in #634
• implement new field: x-go-type-import by @VladimirStepanov in #633
• Fix x-go-type-import code generation by @WesleyMiller1998 in #682
• Correct YAML config example by @jamietanna in #665
• fix: percent in enum values by @corani in #664
• Order request body definitions by content type by @mikesep in #686
• Add option to prefix enum values with their typename by @corani in #662
• Update README config example to use the new schema by @tfaller in #613
• Remove generation of code to handle optional query parameters by @jamietanna in #671
• Fix: Handle unset union map type by @jamietanna in #650
• Allow providing custom error funcs in strict chi server by @chadweimer in #649
• Add test for empty enum value by @tfaller in #612
• Update README to match the new syntax by @lzap in #630
• Fix: gorilla required header error shadowing by @wmarinic in #689
• Allow merging multiple union types by @jamietanna in #670
• Fix readonly+required property by @florentchauveau in #605
• Fix Date (header) param binding by @hslatman in #628
• Generate type names in GoDoc comments by @jamietanna in #601
• Add basic automated builds by @jamietanna in #602
• Allow custom JSON media types to be marked as IsJson by @jamietanna in #582
• handle oapi3.MultiError messages by @joerocklin in #572
• Finish spec documentation by @jamietanna in #706
• Document the README may not be latest tag by @jamietanna in #705
• Correct error message for new flag by @jamietanna in #699
• Add support for strict server with Gorilla by @DouglasDwyer in #716
• Remove io/ioutil by @leonnicolas in #727
• BindStringToObject() allows silent overflow of narrower-than-64-bit numeric types by @danielbprice in #740
• Fix/handle initial digit of http header by @masu-mi in #733
• Strongly typed responses for strict server by @Warboss-rus in #701
• Be more flexible parsing config files. by @deepmap-marcinr in #747
• Ft/remove loop by @masu-mi in #750
• Bump github.com/labstack/echo/v4 from 4.7.2 to 4.9.0 by @dependabot in #767
• Correctly go:generate test client code by @jamietanna in #772
• Fix a bug where strict json decoder is not used. by @Fethbita in #757
• Migrate deprecated io/ioutil package to io and os packages by @mycrEEpy in #755
• Fix docs by @alexpts in #754
• Migrate to tidied by @jamietanna in #725
• Added implementation of x-json-ignore by @sparshev in #390
• Update go to 1.18 by @mycrEEpy in #756
• Default integer data types to int when using custom formats by @bearcherian in #741
• chore: Update dependencies by @mycrEEpy in #780
• cleanup: Remove dependency github.com/cyberdelia/templates by @mycrEEpy in #781
• fixed typo by @kosuke-taniguchi in #779
• fix typo by @nandedamana in #792
• Fix #737: CLI documentation by @nandedamana in #797
• Rewrite imports parsing (issue #760) by @VladimirStepanov in #804
• Add Problem Details content types by @veleek in #802
• fix 794 (no error message for invalid CLI options placed after the in… by @nandedamana in #796
• Generate names with initialisms by @wtertius in #749
• Fixed #719: fix generate for union methods. by @insidieux in #720
• Chain Chi middlewares in reverse order so they execute first-to-last by @ericvolp12 in #787
• chore: Fix comments/imports by @Jleagle in #789
• Add extra JSON type checking by @AnnaDodson in #808
• Ensure embedded spec contains all necessary OpenAPI documents by @jamietanna in #771
• Onboard to Dependabot by @jamietanna in #815
• Bump github.com/stretchr/testify from 1.8.0 to 1.8.1 by @dependabot in #816
• Bump github.com/labstack/echo/v4 from 4.9.0 to 4.9.1 by @dependabot in #818
• Bump golang.org/x/tools from 0.1.12 to 0.2.0 by @dependabot in https://github.com/deepmap/oapi-codege...

Many updates, you will need to update your configuration

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:

oapi-codegen --package=petshop --generate="types,client,server,spec" -alias-types petshop-expanded.yaml

You will now get an error:

error processing flags: flags --alias-types aren't supported in new config style, please use --old-style-config or update your configuration

By adding the --old-config-style, code will be generated:

oapi-codegen --old-config-style  --package=petshop --generate="types,client,server,spec" -alias-types petshop-expanded.yaml

But, we're moving away from flags, so you can generate a config file like so:

oapi-codegen --output-config --old-config-style  --package=petshop --generate="types,client,server,spec" -alias-types petshop-expanded.yaml

And you will see this output:

package: petshop
generate:
  echo-server: true
  client: true
  models: true
  embedded-spec: true

You can save that to a config file, and use that to configure oapi-codegen in the future.

oapi-codegen --config config.yaml petshop-expanded.yaml

Schema merging for allOf has been rewritten

The expanded petstore example contains an allOf schema which merges NewPet properties with an ID:

    Pet:
      allOf:
        - $ref: '#/components/schemas/NewPet'
        - required:
          - id
          properties:
            id:
              type: integer
              format: int64
              description: Unique id of the pet

In the past, we would generate this code:

// Pet defines model for Pet.
type Pet struct {
        // Embedded struct due to allOf(#/components/schemas/NewPet)
        NewPet `yaml:",inline"`
        // Embedded fields due to inline allOf schema
        // Unique id of the pet
        Id int64 `json:"id"`
}

With this release, we generate this:

// Pet defines model for Pet.
type Pet struct {
	// Unique id of the pet
	Id int64 `json:"id"`

	// Name of the pet
	Name string `json:"name"`

	// Type of the pet
	Tag *string `json:"tag,omitempty"`
}

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:

compatibility:
  old-merge-schemas: true

$ref prefers type aliasing

In prior releases, a $ref to another type would create a type declaration.

Say that we have this spec fragment:

components:
  schemas:
    Something:
        type: object
    SomethingElse:
        $ref: "#/components/schemas/Something"

Prior releases would generate:

type Something  interface{}

type SomethingElse Something

This release will generate:

type Something interface{}

type SomethingElse = Something

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:

compatibility:
  old-aliasing: true

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:

components:
  schemas:
        Enum1:
      type: string
      enum: [One, Two, Three]
    Enum2:
      type: string
      enum: [ One, Two, Three ]

Previously, we would generate non-compiling code:

// Defines values for Enum1.
const (
	One   Enum1 = "One"
	Three Enum1 = "Three"
	Two   Enum1 = "Two"
)

// Defines values for Enum2.
const (
	One   Enum2 = "One"
	Three Enum2 = "Three"
	Two   Enum2 = "Two"
)

Now, we generate:

// Defines values for Enum1.
const (
	Enum1One   Enum1 = "One"
	Enum1Three Enum1 = "Three"
	Enum1Two   Enum1 = "Two"
)

// Defines values for Enum2.
const (
	Enum2One   Enum2 = "One"
	Enum2Three Enum2 = "Three"
	Enum2Two   Enum2 = "Two"
)

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:

compatibility:
  old-enum-conflicts: true

What's Changed

• Swap UUID format to byte array by @rliebz in #556
• Update gin example to use most recent release changes by @ericvolp12 in #554
• Add gin to imports template by @mateuszlewko in #560
• Make UUID an alias of uuid.UUID by @Sh4rK in #571
• Add ErrorHandler for middleware by @andrewstucki in #557
• Fix: Unsigned values as parameters by @anoryx in #535
• fix(response): added an option to override the response suffix by @wolfeidau in #493
• Use lower-cased x-go-name for parameters var name by @emilekm in #574
• Apply syntax highlighting to SecurityProvider documentation by @jamietanna in #576

New Contributors

• @rliebz made their first contribution in #556
• @ericvolp12 made their first contribution in #554
• @mateuszlewko made their first contribution in #560
• @Sh4rK made their first contribution in #571
• @andrewstucki made their first contribution in #557
• @anoryx made their first contribution in #535
• @jamietanna made their first contribution in #576

Full Changelog: v1.10.1...v1.11.0

Roll back v1.10.0 Gin changes

PR #530 was a breaking change I should not have merged.

Some new features and many bug fixes

Thank you everyone for your PR's. I'm incrementing the minor version because some new functionality was added:

• x-go-type (#517)
• UUID formatted strings (#546)
• readOnly/writeOnly properties (#547)

I've also merged numerous bug fixes.

Sorry for the long delay in releases, I've been extremely busy, and it takes time to go over PR's to make sure they don't break something.

Bug fixes, go embed for templates

• Update Echo to fix security issues and baseurl handling
• Internally, use go:embed instead of third party embedding tools for templates.

Gin support, auth example, bug fixes

We're increasing the minor version to 1.9.0 since there's new support for Gin and some new libraries in pkg/runtime.

Thanks for all the contributions.

Bug fixes

• Merged a number of PR's fixing various bugs in code generation. Thank you all.

Many bug fixes

I merged quite a few formatting and bug fixes, thanks everyone.

Revert a breaking change

• I reverted the fix for #380 because it changes behavior in a very fragile area. I will revisit this in the future. This fixes the build, for tooling that requires our tests to pass.