README
¶
oapi-codegen V3
This is an experimental prototype of a V3 version of oapi-codegen. The generated code and command line options are not yet stable. Use at your own risk.
What is new in Version 3
This directory contains an experimental version of oapi-codegen's future V3 version, which is based on libopenapi, instead of the prior kin-openapi. This change necessitated a nearly complete rewrite, but we strive to be as compatible as possible.
What is working:
- All model, client and server generation as in earlier versions.
- We have added Webhook and Callback support, please see
./examples, which contains the ubiquitous OpenAPI pet shop implemented in all supported servers and examples of webhooks and callbacks implemented on top of thehttp.ServeMuxserver, with no additional imports. - Echo V5 support has been added (Go 1.25 required)
- The
runtimehas changed a lot. By default, we generate all the needed runtime functions into your generated code. You can, optionally, generate your own runtime package locally, to avoid duplication between multiple openapi specifications. This was done because the version pinning between runtime and the codegen was exceedingly annoying, so now, the runtime is embedded into the generator itself, and there is no versioning issue.
What is missing:
- Middleware, this is for someone else to solve.
- Good documentation. You'll have to read over the config file code to see how to configure.
Differences in V3
V3 is a brand new implementation, and may (will) contain new bugs, but also strives to fix many current, existing bugs. We've run quite a few conformance tests against specifications in old Issues, and we're looking pretty good! Please try this out, and if it failes in some way, please file Issues.
Normalized extension names
V3 normalizes all extension names under the x-oapi-codegen- prefix. The old names are still accepted for backwards compatibility.
| V2 | This version | Scope | Purpose |
|---|---|---|---|
x-go-type + x-go-type-import |
x-oapi-codegen-type-override |
Schema, Property | Use an external Go type instead of generating one. V3 combines type and import into a single value: "TypeName;import/path". |
x-go-name |
x-oapi-codegen-name-override |
Property | Override the generated Go field name. |
x-go-type-name |
x-oapi-codegen-type-name-override |
Schema | Override the generated Go type name. |
x-go-type-skip-optional-pointer |
x-oapi-codegen-skip-optional-pointer |
Property | Don't wrap optional fields in a pointer. |
x-go-json-ignore |
x-oapi-codegen-json-ignore |
Property | Exclude the field from JSON (json:"-"). |
x-omitempty |
x-oapi-codegen-omitempty |
Property | Explicitly control the omitempty JSON tag. |
x-omitzero |
x-oapi-codegen-omitzero |
Property | Add omitzero to the JSON tag (Go 1.24+ encoding/json/v2). |
x-enum-varnames / x-enumNames |
x-oapi-codegen-enum-varnames |
Schema (enum) | Override generated enum constant names. |
x-deprecated-reason |
x-oapi-codegen-deprecated-reason |
Schema, Operation | Provide a deprecation reason for documentation. |
x-order |
x-oapi-codegen-order |
Property | Control field ordering in generated structs. |
OpenAPI V3.1 Feature Support
Thanks to libopenapi, we are able to parse OpenAPI 3.1 and 3.2 specifications. They are functionally similar, you can
read the differences between nullable fields yourself, but they add some new functionality, namely webhooks and callbacks. We support all of them in
this prototype. callbacks and webhooks are basically the inverse of paths. Webhooks contain no URL element in their definition, so we can't register handlers
for you in your http router of choice, you have to do that yourself. Callbacks support complex request URL's which may reference the original request. This is
something you need to pull out of the request body, and doing it generically is difficult, so we punt this problem, for now, to our users.
Please see the webhook example. It creates a little server that pretends to be a door badge reader, and it generates an event stream about people coming and going. Any number of clients may subscribe to this event. See the doc.go for usage examples.
The callback example, creates a little server that pretends to plant trees. Each tree planting request contains a callback to be notified when tree planting is complete. We invoke those in a random order via delays, and the client prints out callbacks as they happen. Please see doc.go for usage.
Flexible Configuration
oapi-codegen V3 tries to make no assumptions about which initialisms, struct tags, or name mangling that is correct for you. A very flexible configuration file allows you to override anything.
No runtime dependency
V2 generated code relied on github.com/oapi-codegen/runtime for parameter binding and styling. This was a complaint from lots of people due to various
audit requirements. V3 embeds all necessary helper functions and helper types into the spec. There are no longer generic, parameterized functions that
handle arbitrary parameters, but rather very specific functions for each kind of parameter, and we call the correct little helper versus a generic
runtime helper.
We still use the code generator to produce a pre-generated runtime package, which you are
welcome to use. It will always be consistent with the code generated with the corresponding
oapi-codegen. If you have lots of OpenAPI specs locally, you can also generate the runtime
package, as we do, in your own code to avoid bloat.
Models now support default values configured in the spec
Every model which we generate supports an ApplyDefaults() function. It recursively applies defaults on
any unset optional fields. There's a little caveat here, in that some types are external references, so
we call ApplyDefaults() on them via reflection. This might call an ApplyDefaults() which is completely
unrelated to what we're doing. Please let me know if this feature is causing trouble.
Installation
Go 1.25 is required, install like so:
go get -tool github.com/oapi-codegen/oapi-codegen-exp/experimental/cmd/oapi-codegen@latest
You can then run the code generator
//go:generate go run github.com/oapi-codegen/oapi-codegen-exp/experimental/cmd/oapi-codegen
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
oapi-codegen
command
|
|
|
Package codegen provides the public API for oapi-codegen's experimental code generator.
|
Package codegen provides the public API for oapi-codegen's experimental code generator. |
|
internal
Package codegen generates Go code from parsed OpenAPI specs.
|
Package codegen generates Go code from parsed OpenAPI specs. |
|
internal/dce
Package dce implements dead code elimination for generated Go source files.
|
Package dce implements dead code elimination for generated Go source files. |
|
internal/runtime
Package runtime contains the source-of-truth Go source files for the oapi-codegen runtime helpers.
|
Package runtime contains the source-of-truth Go source files for the oapi-codegen runtime helpers. |
|
internal/runtimeextract
Package runtimeextract reads Go source files from the embedded runtime FS and extracts code bodies for inlining into generated output or assembling into standalone runtime packages.
|
Package runtimeextract reads Go source files from the embedded runtime FS and extracts code bodies for inlining into generated output or assembling into standalone runtime packages. |
|
internal/test/_parked/all_of
Package all_of tests allOf schema composition from the V2 test suite.
|
Package all_of tests allOf schema composition from the V2 test suite. |
|
internal/test/_parked/any_of/inline
Package inline tests inline anyOf schema composition from the V2 test suite.
|
Package inline tests inline anyOf schema composition from the V2 test suite. |
|
internal/test/_parked/any_of/param
Package param tests anyOf/oneOf in parameters from the V2 test suite.
|
Package param tests anyOf/oneOf in parameters from the V2 test suite. |
|
internal/test/_parked/issue_1029
Package issue_1029 tests that oneOf with multiple single-value string enums generates valid code.
|
Package issue_1029 tests that oneOf with multiple single-value string enums generates valid code. |
|
internal/test/_parked/issue_1189
Package issue_1189 tests anyOf/allOf/oneOf composition.
|
Package issue_1189 tests anyOf/allOf/oneOf composition. |
|
internal/test/_parked/issue_1219
Package issue_1219 tests additionalProperties merge with allOf.
|
Package issue_1219 tests additionalProperties merge with allOf. |
|
internal/test/_parked/issue_1429
Package issue_1429 tests that enums inside anyOf members are generated.
|
Package issue_1429 tests that enums inside anyOf members are generated. |
|
internal/test/_parked/issue_1710
Package issue_1710 tests that fields are not lost in nested allOf oneOf structures.
|
Package issue_1710 tests that fields are not lost in nested allOf oneOf structures. |
|
internal/test/_parked/issue_193
Package issue_193 tests allOf with additionalProperties merging.
|
Package issue_193 tests allOf with additionalProperties merging. |
|
internal/test/_parked/issue_2102
Package issue_2102 tests that properties defined at the same level as allOf are included.
|
Package issue_2102 tests that properties defined at the same level as allOf are included. |
|
internal/test/_parked/issue_502
Package issue_502 tests that anyOf with only one ref generates the referenced type.
|
Package issue_502 tests that anyOf with only one ref generates the referenced type. |
|
internal/test/_parked/issue_697
Package issue_697 tests that properties alongside allOf are included.
|
Package issue_697 tests that properties alongside allOf are included. |
|
internal/test/_parked/issue_775
Package issue_775 tests that allOf with format specification works correctly.
|
Package issue_775 tests that allOf with format specification works correctly. |
|
internal/test/_parked/issue_936
Package issue_936 tests recursive/circular schema references.
|
Package issue_936 tests recursive/circular schema references. |
|
internal/test/callbacks
Package callbacks tests callback initiator and receiver code generation.
|
Package callbacks tests callback initiator and receiver code generation. |
|
internal/test/components/composition
Package composition tests complex component schemas including additionalProperties, oneOf/anyOf patterns, enums, readOnly/writeOnly, and x-go-name.
|
Package composition tests complex component schemas including additionalProperties, oneOf/anyOf patterns, enums, readOnly/writeOnly, and x-go-name. |
|
internal/test/components/default_values
Package default_values tests default value handling in generated types.
|
Package default_values tests default value handling in generated types. |
|
internal/test/components/enums/illegal_names
Package illegal_names tests enum constant generation with edge cases.
|
Package illegal_names tests enum constant generation with edge cases. |
|
internal/test/components/nullable
Package nullable tests nullable type generation with required/optional combinations.
|
Package nullable tests nullable type generation with required/optional combinations. |
|
internal/test/components/objects
Package objects tests object schemas with additionalProperties configurations.
|
Package objects tests object schemas with additionalProperties configurations. |
|
internal/test/components/primitives/aliased_date
Package aliased_date tests aliased date-format types.
|
Package aliased_date tests aliased date-format types. |
|
internal/test/components/primitives/untyped_properties
Package untyped_properties tests properties with no type field.
|
Package untyped_properties tests properties with no type field. |
|
internal/test/components/recursive
Package recursive tests that recursive types are handled properly.
|
Package recursive tests that recursive types are handled properly. |
|
internal/test/components/schemas
Package schemas tests comprehensive schema generation including generic objects, nullable properties, custom formats, extra-tags, deprecated fields, and x-go-type-name.
|
Package schemas tests comprehensive schema generation including generic objects, nullable properties, custom formats, extra-tags, deprecated fields, and x-go-type-name. |
|
internal/test/extensions/x_go_type/enum_override
Package enum_override tests x-go-type-name on enum types.
|
Package enum_override tests x-go-type-name on enum types. |
|
internal/test/extensions/x_go_type/object_override
Package object_override tests x-go-type-name on nested object types.
|
Package object_override tests x-go-type-name on nested object types. |
|
internal/test/extensions/x_go_type/skip_pointer
Package skip_pointer tests x-go-type with skip-optional-pointer and x-go-type-import.
|
Package skip_pointer tests x-go-type with skip-optional-pointer and x-go-type-import. |
|
internal/test/extensions/x_order
Package x_order tests field ordering via x-order extension.
|
Package x_order tests field ordering via x-order extension. |
|
internal/test/external_ref/imports
Package imports tests external dependencies with import resolution.
|
Package imports tests external dependencies with import resolution. |
|
internal/test/external_ref/multi_package_response
Package multi_package_response tests multi-package response schemas.
|
Package multi_package_response tests multi-package response schemas. |
|
internal/test/external_ref/multi_spec
Package multi_spec tests multi-spec cross-package imports.
|
Package multi_spec tests multi-spec cross-package imports. |
|
internal/test/external_ref/overlays
Package overlays tests spec overlays and external refs.
|
Package overlays tests spec overlays and external refs. |
|
internal/test/external_ref/removed_ref
Package removed_ref tests external reference filtering.
|
Package removed_ref tests external reference filtering. |
|
internal/test/external_ref/response_refs
Package response_refs tests external response refs across specs.
|
Package response_refs tests external response refs across specs. |
|
internal/test/name_conflict_resolution
Package name_conflict_resolution tests comprehensive type name collision resolution.
|
Package name_conflict_resolution tests comprehensive type name collision resolution. |
|
internal/test/name_conflict_resolution/head_digit_op_id
Package head_digit_op_id tests operation IDs starting with digits.
|
Package head_digit_op_id tests operation IDs starting with digits. |
|
internal/test/name_conflict_resolution/inline_identifiers
Package inline_identifiers tests that inline schemas generate valid Go identifiers.
|
Package inline_identifiers tests that inline schemas generate valid Go identifiers. |
|
internal/test/name_conflict_resolution/underscore_mapping
Package underscore_mapping tests underscore field name mapping.
|
Package underscore_mapping tests underscore field name mapping. |
|
internal/test/output_options/name_normalizer
Package name_normalizer tests name normalization behavior.
|
Package name_normalizer tests name normalization behavior. |
|
internal/test/output_options/skip_optional_pointer/arrays
Package arrays tests skip-optional-pointer with arrays and additionalProperties.
|
Package arrays tests skip-optional-pointer with arrays and additionalProperties. |
|
internal/test/output_options/skip_optional_pointer/containers
Package containers tests skip-optional-pointer on container types.
|
Package containers tests skip-optional-pointer on container types. |
|
internal/test/output_options/skip_prune
Package skip_prune tests skip-prune configuration for unreferenced schemas.
|
Package skip_prune tests skip-prune configuration for unreferenced schemas. |
|
internal/test/parameters/all_styles
Package all_styles tests parameter type generation across all locations and styles.
|
Package all_styles tests parameter type generation across all locations and styles. |
|
internal/test/parameters/encoding
Package encoding tests path parameter escaping and special characters.
|
Package encoding tests path parameter escaping and special characters. |
|
internal/test/parameters/precedence
Package precedence tests operation-level parameters overriding path-level parameters.
|
Package precedence tests operation-level parameters overriding path-level parameters. |
|
internal/test/request_response/content_types/custom_json
Package custom_json tests custom JSON content types (application/test+json).
|
Package custom_json tests custom JSON content types (application/test+json). |
|
internal/test/request_response/content_types/custom_schema
Package custom_schema tests custom content-type schema handling.
|
Package custom_schema tests custom content-type schema handling. |
|
internal/test/request_response/content_types/multiple
Package multiple tests multiple content types in responses.
|
Package multiple tests multiple content types in responses. |
|
internal/test/webhooks
Package webhooks tests webhook initiator and receiver code generation.
|
Package webhooks tests webhook initiator and receiver code generation. |
|
examples
|
|
|
callback
Package treefarm provides an example of how to handle OpenAPI callbacks.
|
Package treefarm provides an example of how to handle OpenAPI callbacks. |
|
callback/client
command
|
|
|
callback/server
command
|
|
|
petstore-expanded
Package petstore provides generated types for the Petstore API.
|
Package petstore provides generated types for the Petstore API. |
|
webhook
Package doorbadge provides an example of OpenAPI 3.1 webhooks.
|
Package doorbadge provides an example of OpenAPI 3.1 webhooks. |
|
webhook/client
command
|
|
|
webhook/server
command
|
|
|
Package runtime provides shared helper types and functions for code generated by oapi-codegen.
|
Package runtime provides shared helper types and functions for code generated by oapi-codegen. |