v2.1.0: Nullable, external reference improvements, x-order, and many more!

[jamietanna]

🔊 Notable features

Nullable types

It's possible that you want to be able to determine whether a field isn't sent, is sent as null or has a value.

For instance, if you had the following OpenAPI property:

S:
  type: object
  properties:
    Field:
      type: string
      nullable: true
    required: []

The current behaviour in oapi-codegen is to generate:

type S struct {
	Field *string `json:"field,omitempty"`
}

However, you lose the ability to understand the three cases, as there's no way to distinguish two of the types from each other:

• is this field not sent? (Can be checked with S.Field == nil)
• is this field null? (Can be checked with S.Field == nil)
• does this field have a value? (S.Field != nil && *S.Field == "123")

Therefore, as requested in #1039, this is now possible to represent with the nullable.Nullable type from our new library, oapi-codegen/nullable.

If you configure your generator's Output Options as so:

output-options:
  nullable-type: true

You will now receive the following output:

type S struct {
    Field nullable.Nullable[string] `json:"field,omitempty"`
}

Note that this is opt-in only, due to it being a break in existing signatures and behaviour.

You can find out more about how this works in a blog post with further details.

External references are now handled better

A big change has come in which handling of external references (also called import mappings) is much more resilient and predictable for generated code.

This allows cases where multiple files referencing each other (for instance if you've split your API across multiple files, and join them using $refs) now correctly generate code.

There are a few cases that won't be covered, that we'll complete in #1440 but until then, it hopefully should work better.

Thank you to Ejendomstorvet for sponsoring this work.

🚀 New features and improvements

• Add support for x-order extension (Add support for x-order extension #1190) @filintod
• Make arrays use concrete types, not aliases. (Make arrays use concrete types, not aliases. #1246) @jkj
• feat: filter by operation ids (feat: filter by operation ids #929) @johanneswuerbach
• Allow generating nullable.Nullable for nullable properties (Allow generating nullable.Nullable for nullable properties #1404) @sonasingh46
• Support media type parameters for IsMediaTypeJson (Support media type parameters for IsMediaTypeJson #1386) @jamietanna
• Pass .Required to BindStyledParameterWithLocation and BindStyledParameter (Pass .Required to BindStyledParameterWithLocation and BindStyledParameter #1315) @renom

🐛 Bug fixes

• Fix: Ensure external refs are propagated to generated code (Fix: Ensure external refs are propagated to generated code #1389) @jamietanna
• Fix: Refer to external refs correctly in strict interfaces (Fix: Refer to external refs correctly in strict interfaces #1387) @jamietanna
• refactor(cmd): Use os.Exit(1) only from main() (refactor(cmd): Use os.Exit(1) only from main() #1398) @alexandear
• Fix binding for JSON body (Fix binding for JSON body #1299) @ShouheiNishi
• Fix: Handle code generation for all multipart content-types (Fix: Handle code generation for all multipart content-types #1385) @ShouheiNishi
• Pass .Required to BindStyledParameterWithLocation and BindStyledParameter (Pass .Required to BindStyledParameterWithLocation and BindStyledParameter #1315) @renom

📝 Documentation updates

• Fixes confusing indentation for example code in README.md (Fixes confusing indentation for example code in README.md #1414) @mtskg
• Document how to use import-mapping with URLs (Document how to use import-mapping with URLs #1428) @jamietanna
• Fix typo in README.md (Fix typo in README.md #1351) @eltociear

👻 Maintenance

• Fix typos in flag, tests, doc, and comments (Fix typos in flag, tests, doc, and comments #1287) @alexandear
• add unit tests for go type gen function (add unit tests for go type gen function #1423) @sonasingh46
• Use non-deprecated function names for oapi-codegen/runtime (Use non-deprecated function names for oapi-codegen/runtime #1359) @cimitan
• Onboard to Release Drafter (Onboard to Release Drafter #1350) @jamietanna

📦 Dependency updates

• Update module github.com/golangci/golangci-lint to v1.55.2 (Update module github.com/golangci/golangci-lint to v1.55.2 #1285) @renovate
• feat: bump github.com/getkin/kin-openapi to v0.122.0 (feat: bump github.com/getkin/kin-openapi to v0.122.0 #1364) @chrisgacsal
• Update module golang.org/x/text to v0.14.0 (Update module golang.org/x/text to v0.14.0 #1349) @renovate

New Contributors

• @renom made their first contribution in Pass .Required to BindStyledParameterWithLocation and BindStyledParameter #1315
• @eltociear made their first contribution in Fix typo in README.md #1351
• @chrisgacsal made their first contribution in feat: bump github.com/getkin/kin-openapi to v0.122.0 #1364
• @cimitan made their first contribution in Use non-deprecated function names for oapi-codegen/runtime #1359
• @sonasingh46 made their first contribution in add unit tests for go type gen function #1423
• @mtskg made their first contribution in Fixes confusing indentation for example code in README.md #1414
• @jkj made their first contribution in Make arrays use concrete types, not aliases. #1246
• @filintod made their first contribution in Add support for x-order extension #1190

---

This discussion was created from the release v2.1.0: Nullable, external reference improvements, x-order, and many more!.