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/cmd/oapi-codegen@latest
You can then run the code generator
//go:generate go run github.com/oapi-codegen/oapi-codegen-exp/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/callbacks
Package callbacks tests callback initiator and receiver code generation.
|
Package callbacks tests callback initiator and receiver code generation. |
|
internal/test/components/all_of
Package all_of tests allOf schema composition including inheritance chains, required field merging, and nested allOf with additional properties.
|
Package all_of tests allOf schema composition including inheritance chains, required field merging, and nested allOf with additional properties. |
|
internal/test/components/allof_with_properties/additional_properties
Package additional_properties tests allOf composition where members have additionalProperties: true.
|
Package additional_properties tests allOf composition where members have additionalProperties: true. |
|
internal/test/components/allof_with_properties/additional_properties_merge
Package additional_properties_merge tests all combinations of allOf merging with different additionalProperties configurations (true, false, typed, default).
|
Package additional_properties_merge tests all combinations of allOf merging with different additionalProperties configurations (true, false, typed, default). |
|
internal/test/components/allof_with_properties/format
Package format tests allOf used to apply format constraints (uuid, date) to a base string type.
|
Package format tests allOf used to apply format constraints (uuid, date) to a base string type. |
|
internal/test/components/allof_with_properties/same_level
Package same_level tests that properties defined at the same level as allOf are included in the generated type, not ignored.
|
Package same_level tests that properties defined at the same level as allOf are included in the generated type, not ignored. |
|
internal/test/components/any_of_enums
Package any_of_enums tests that enum types are generated for properties inside anyOf member schemas.
|
Package any_of_enums tests that enum types are generated for properties inside anyOf member schemas. |
|
internal/test/components/any_of_inline
Package any_of_inline tests inline anyOf schema composition with response schemas containing multiple object variants.
|
Package any_of_inline tests inline anyOf schema composition with response schemas containing multiple object variants. |
|
internal/test/components/any_of_single_ref
Package any_of_single_ref tests anyOf with a single $ref — should generate a typed property, not interface{}.
|
Package any_of_single_ref tests anyOf with a single $ref — should generate a typed property, not interface{}. |
|
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/nested_aggregate
Package nested_aggregate tests complex nesting of allOf, anyOf, and oneOf: arrays of anyOf, objects with anyOf/oneOf properties, allOf containing oneOf, oneOf with nested allOf and field preservation, and composition with enums.
|
Package nested_aggregate tests complex nesting of allOf, anyOf, and oneOf: arrays of anyOf, objects with anyOf/oneOf properties, allOf containing oneOf, oneOf with nested allOf and field preservation, and composition with enums. |
|
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/one_of_discriminator_multi_mapping
Package one_of_discriminator_multi_mapping tests oneOf with a discriminator having multiple mapping entries pointing to the same schema.
|
Package one_of_discriminator_multi_mapping tests oneOf with a discriminator having multiple mapping entries pointing to the same schema. |
|
internal/test/components/one_of_string_enums
Package one_of_string_enums tests oneOf with single-value string enum variants (undefined, registered, pending, active).
|
Package one_of_string_enums tests oneOf with single-value string enum variants (undefined, registered, pending, active). |
|
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/recursive_all_of
Package recursive_all_of tests recursive allOf self-references in schema definitions without causing a stack overflow.
|
Package recursive_all_of tests recursive allOf self-references in schema definitions without causing a stack overflow. |
|
internal/test/components/recursive_one_of
Package recursive_one_of tests recursive/circular oneOf schema references (FilterPredicate pattern).
|
Package recursive_one_of tests recursive/circular oneOf schema references (FilterPredicate pattern). |
|
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/any_of
Package any_of tests anyOf and oneOf types used in query parameters, including complex object schemas and primitive type unions.
|
Package any_of tests anyOf and oneOf types used in query parameters, including complex object schemas and primitive type unions. |
|
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/parameters/roundtrip/client
Package client contains the generated client for the parameter roundtrip test.
|
Package client contains the generated client for the parameter roundtrip test. |
|
internal/test/parameters/roundtrip/stdhttp
Package stdhttp contains the std-http server for the parameter roundtrip test.
|
Package stdhttp contains the std-http server for the parameter roundtrip test. |
|
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
|
|
|
experimental
module
|
|
|
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. |
Click to show internal directories.
Click to hide internal directories.