| +Extension + | ++Description + | ++Example usage + | +
|---|---|---|
|
+
+`x-go-type` +`x-go-type-import` + + |
++Override the generated type definition (and optionally, add an import from another package) + | +
+
+
+Using the `x-go-type` (and optionally, `x-go-type-import` when you need to import another package) allows overriding the type that `oapi-codegen` determined the generated type should be.
+
+We can see this at play with the following schemas:
+
+```yaml
+components:
+ schemas:
+ Client:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ id:
+ type: number
+ ClientWithExtension:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ # this is a bit of a contrived example, as you could instead use
+ # `format: uuid` but it explains how you'd do this when there may be
+ # a clash, for instance if you already had a `uuid` package that was
+ # being imported, or ...
+ x-go-type: googleuuid.UUID
+ x-go-type-import:
+ path: github.com/google/uuid
+ name: googleuuid
+ id:
+ type: number
+ # ... this is also a bit of a contrived example, as you could use
+ # `type: integer` but in the case that you know better than what
+ # oapi-codegen is generating, like so:
+ x-go-type: int64
+```
+
+From here, we now get two different models:
+
+```go
+// Client defines model for Client.
+type Client struct {
+ Id *float32 `json:"id,omitempty"`
+ Name string `json:"name"`
+}
+
+// ClientWithExtension defines model for ClientWithExtension.
+type ClientWithExtension struct {
+ Id *int64 `json:"id,omitempty"`
+ Name googleuuid.UUID `json:"name"`
+}
+```
+
+You can see this in more detail in [the example code](examples/extensions/xgotype/).
+
+
+ |
+
| + +`x-go-type-skip-optional-pointer` + + | ++Do not add a pointer type for optional fields in structs + | +
+
+
+By default, `oapi-codegen` will generate a pointer for optional fields.
+
+Using the `x-go-type-skip-optional-pointer` extension allows omitting that pointer.
+
+We can see this at play with the following schemas:
+
+```yaml
+components:
+ schemas:
+ Client:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ id:
+ type: number
+ ClientWithExtension:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ id:
+ type: number
+ x-go-type-skip-optional-pointer: true
+```
+
+From here, we now get two different models:
+
+```go
+// Client defines model for Client.
+type Client struct {
+ Id *float32 `json:"id,omitempty"`
+ Name string `json:"name"`
+}
+
+// ClientWithExtension defines model for ClientWithExtension.
+type ClientWithExtension struct {
+ Id float32 `json:"id,omitempty"`
+ Name string `json:"name"`
+}
+```
+
+You can see this in more detail in [the example code](examples/extensions/xgotypeskipoptionalpointer/).
+
+
+ |
+
| + +`x-go-name` + + | ++Override the generated name of a field or a type + | +
+
+
+By default, `oapi-codegen` will attempt to generate the name of fields and types in as best a way it can.
+
+However, sometimes, the name doesn't quite fit what your codebase standards are, or the intent of the field, so you can override it with `x-go-name`.
+
+We can see this at play with the following schemas:
+
+```yaml
+openapi: "3.0.0"
+info:
+ version: 1.0.0
+ title: x-go-name
+components:
+ schemas:
+ Client:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ id:
+ type: number
+ ClientWithExtension:
+ type: object
+ # can be used on a type
+ x-go-name: ClientRenamedByExtension
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ id:
+ type: number
+ # or on a field
+ x-go-name: AccountIdentifier
+```
+
+From here, we now get two different models:
+
+```go
+// Client defines model for Client.
+type Client struct {
+ Id *float32 `json:"id,omitempty"`
+ Name string `json:"name"`
+}
+
+// ClientRenamedByExtension defines model for ClientWithExtension.
+type ClientRenamedByExtension struct {
+ AccountIdentifier *float32 `json:"id,omitempty"`
+ Name string `json:"name"`
+}
+```
+
+You can see this in more detail in [the example code](examples/extensions/xgoname/).
+
+
+ |
+
| + +`x-go-type-name` + + | ++Override the generated name of a type + | +
+
+
+> [!NOTE]
+> Notice that this is subtly different to the `x-go-name`, which also applies to _fields_ within `struct`s.
+
+By default, `oapi-codegen` will attempt to generate the name of types in as best a way it can.
+
+However, sometimes, the name doesn't quite fit what your codebase standards are, or the intent of the field, so you can override it with `x-go-name`.
+
+We can see this at play with the following schemas:
+
+```yaml
+openapi: "3.0.0"
+info:
+ version: 1.0.0
+ title: x-go-type-name
+components:
+ schemas:
+ Client:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ id:
+ type: number
+ ClientWithExtension:
+ type: object
+ x-go-type-name: ClientRenamedByExtension
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ id:
+ type: number
+ # NOTE attempting a `x-go-type-name` here is a no-op, as we're not producing a _type_ only a _field_
+ x-go-type-name: ThisWillNotBeUsed
+```
+
+From here, we now get two different models and a type alias:
+
+```go
+// Client defines model for Client.
+type Client struct {
+ Id *float32 `json:"id,omitempty"`
+ Name string `json:"name"`
+}
+
+// ClientWithExtension defines model for ClientWithExtension.
+type ClientWithExtension = ClientRenamedByExtension
+
+// ClientRenamedByExtension defines model for .
+type ClientRenamedByExtension struct {
+ Id *float32 `json:"id,omitempty"`
+ Name string `json:"name"`
+}
+```
+
+You can see this in more detail in [the example code](examples/extensions/xgotypename/).
+
+
+ |
+
| + +`x-omitempty` + + | ++Force the presence of the JSON tag `omitempty` on a field + | +
+
+
+In a case that you may want to add the JSON struct tag `omitempty` to types that don't have one generated by default - for instance a required field - you can use the `x-omitempty` extension.
+
+We can see this at play with the following schemas:
+
+```yaml
+openapi: "3.0.0"
+info:
+ version: 1.0.0
+ title: x-omitempty
+components:
+ schemas:
+ Client:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ id:
+ type: number
+ ClientWithExtension:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ # for some reason, you may want this behaviour, even though it's a required field
+ x-omitempty: true
+ id:
+ type: number
+```
+
+From here, we now get two different models:
+
+```go
+// Client defines model for Client.
+type Client struct {
+ Id *float32 `json:"id,omitempty"`
+ Name string `json:"name"`
+}
+
+// ClientWithExtension defines model for ClientWithExtension.
+type ClientWithExtension struct {
+ Id *float32 `json:"id,omitempty"`
+ Name string `json:"name,omitempty"`
+}
+```
+
+Notice that the `ComplexField` is still generated in full, but the type will then be ignored with JSON marshalling.
+
+You can see this in more detail in [the example code](examples/extensions/xgojsonignore/).
+
+
+ |
+
| + +`x-go-json-ignore` + + | ++When (un)marshaling JSON, ignore field(s) + | +
+
+
+By default, `oapi-codegen` will generate `json:"..."` struct tags for all fields in a struct, so JSON (un)marshaling works.
+
+However, sometimes, you want to omit fields, which can be done with the `x-go-json-ignore` extension.
+
+We can see this at play with the following schemas:
+
+```yaml
+openapi: "3.0.0"
+info:
+ version: 1.0.0
+ title: x-go-json-ignore
+components:
+ schemas:
+ Client:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ complexField:
+ type: object
+ properties:
+ name:
+ type: string
+ accountName:
+ type: string
+ # ...
+ ClientWithExtension:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ complexField:
+ type: object
+ properties:
+ name:
+ type: string
+ accountName:
+ type: string
+ # ...
+ x-go-json-ignore: true
+```
+
+From here, we now get two different models:
+
+```go
+// Client defines model for Client.
+type Client struct {
+ ComplexField *struct {
+ AccountName *string `json:"accountName,omitempty"`
+ Name *string `json:"name,omitempty"`
+ } `json:"complexField,omitempty"`
+ Name string `json:"name"`
+}
+
+// ClientWithExtension defines model for ClientWithExtension.
+type ClientWithExtension struct {
+ ComplexField *struct {
+ AccountName *string `json:"accountName,omitempty"`
+ Name *string `json:"name,omitempty"`
+ } `json:"-"`
+ Name string `json:"name"`
+}
+```
+
+Notice that the `ComplexField` is still generated in full, but the type will then be ignored with JSON marshalling.
+
+You can see this in more detail in [the example code](examples/extensions/xgojsonignore/).
+
+
+ |
+
| + +`x-oapi-codegen-extra-tags` + + | ++Generate arbitrary struct tags to fields + | +
+
+
+If you're making use of a field's struct tags to i.e. apply validation, decide whether something should be logged, etc, you can use `x-oapi-codegen-extra-tags` to set additional tags for your generated types.
+
+We can see this at play with the following schemas:
+
+```yaml
+openapi: "3.0.0"
+info:
+ version: 1.0.0
+ title: x-oapi-codegen-extra-tags
+components:
+ schemas:
+ Client:
+ type: object
+ required:
+ - name
+ - id
+ properties:
+ name:
+ type: string
+ id:
+ type: number
+ ClientWithExtension:
+ type: object
+ required:
+ - name
+ - id
+ properties:
+ name:
+ type: string
+ id:
+ type: number
+ x-oapi-codegen-extra-tags:
+ validate: "required,min=1,max=256"
+ safe-to-log: "true"
+ gorm: primarykey
+```
+
+From here, we now get two different models:
+
+```go
+// Client defines model for Client.
+type Client struct {
+ Id float32 `json:"id"`
+ Name string `json:"name"`
+}
+
+// ClientWithExtension defines model for ClientWithExtension.
+type ClientWithExtension struct {
+ Id float32 `gorm:"primarykey" json:"id" safe-to-log:"true" validate:"required,min=1,max=256"`
+ Name string `json:"name"`
+}
+```
+
+You can see this in more detail in [the example code](examples/extensions/xoapicodegenextratags/).
+
+
+ |
+
| + +`x-enum-varnames` / `x-enumNames` + + | ++Override generated variable names for enum constants + | +
+
+
+When consuming an enum value from an external system, the name may not produce a nice variable name. Using the `x-enum-varnames` extension allows overriding the name of the generated variable names.
+
+We can see this at play with the following schemas:
+
+```yaml
+openapi: "3.0.0"
+info:
+ version: 1.0.0
+ title: x-enumNames and x-enum-varnames
+components:
+ schemas:
+ ClientType:
+ type: string
+ enum:
+ - ACT
+ - EXP
+ ClientTypeWithNamesExtension:
+ type: string
+ enum:
+ - ACT
+ - EXP
+ x-enumNames:
+ - Active
+ - Expired
+ ClientTypeWithVarNamesExtension:
+ type: string
+ enum:
+ - ACT
+ - EXP
+ x-enum-varnames:
+ - Active
+ - Expired
+```
+
+From here, we now get two different forms of the same enum definition.
+
+```go
+// Defines values for ClientType.
+const (
+ ACT ClientType = "ACT"
+ EXP ClientType = "EXP"
+)
+
+// ClientType defines model for ClientType.
+type ClientType string
+
+// Defines values for ClientTypeWithExtension.
+const (
+ Active ClientTypeWithExtension = "ACT"
+ Expired ClientTypeWithExtension = "EXP"
+)
+
+// ClientTypeWithExtension defines model for ClientTypeWithExtension.
+type ClientTypeWithExtension string
+```
+
+You can see this in more detail in [the example code](examples/extensions/xenumvarnames/).
+
+
+ |
+
| + +`x-deprecated-reason` + + | ++Add a GoDoc deprecation warning to a type + | +
+
+
+When an OpenAPI type is deprecated, a deprecation warning can be added in the GoDoc using `x-deprecated-reason`.
+
+We can see this at play with the following schemas:
+
+```yaml
+openapi: "3.0.0"
+info:
+ version: 1.0.0
+ title: x-deprecated-reason
+components:
+ schemas:
+ Client:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ id:
+ type: number
+ ClientWithExtension:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ deprecated: true
+ x-deprecated-reason: Don't use because reasons
+ id:
+ type: number
+ # NOTE that this doesn't generate, as no `deprecated: true` is set
+ x-deprecated-reason: NOTE you shouldn't see this, as you've not deprecated this field
+```
+
+From here, we now get two different forms of the same enum definition.
+
+```go
+// Client defines model for Client.
+type Client struct {
+ Id *float32 `json:"id,omitempty"`
+ Name string `json:"name"`
+}
+
+// ClientWithExtension defines model for ClientWithExtension.
+type ClientWithExtension struct {
+ Id *float32 `json:"id,omitempty"`
+ // Deprecated: Don't use because reasons
+ Name string `json:"name"`
+}
+```
+
+Notice that because we've not set `deprecated: true` to the `name` field, it doesn't generate a deprecation warning.
+
+You can see this in more detail in [the example code](examples/extensions/xdeprecatedreason/).
+
+
+ |
+
| + +`x-order` + + | ++Explicitly order struct fields + | +
+
+
+Whether you like certain fields being ordered before others, or you want to perform more efficient packing of your structs, the `x-order` extension is here for you.
+
+Note that `x-order` is 1-indexed - `x-order: 0` is not a valid value.
+
+When an OpenAPI type is deprecated, a deprecation warning can be added in the GoDoc using `x-deprecated-reason`.
+
+We can see this at play with the following schemas:
+
+```yaml
+openapi: "3.0.0"
+info:
+ version: 1.0.0
+ title: x-order
+components:
+ schemas:
+ Client:
+ type: object
+ required:
+ - name
+ properties:
+ a_name:
+ type: string
+ id:
+ type: number
+ ClientWithExtension:
+ type: object
+ required:
+ - name
+ properties:
+ a_name:
+ type: string
+ x-order: 2
+ id:
+ type: number
+ x-order: 1
+```
+
+From here, we now get two different forms of the same type definition.
+
+```go
+// Client defines model for Client.
+type Client struct {
+ AName *string `json:"a_name,omitempty"`
+ Id *float32 `json:"id,omitempty"`
+}
+
+// ClientWithExtension defines model for ClientWithExtension.
+type ClientWithExtension struct {
+ Id *float32 `json:"id,omitempty"`
+ AName *string `json:"a_name,omitempty"`
+}
+```
+
+You can see this in more detail in [the example code](examples/extensions/xorder/).
+
+
+ |
+
| +Server + | ++Middleware library + | +
|---|---|
| + +[Chi](https://github.com/go-chi/chi) + + | ++ +[nethttp-middleware](https://github.com/oapi-codegen/nethttp-middleware) + + | +
| + +[Echo](https://github.com/labstack/echo) + + | ++ +[echo-middleware](https://github.com/oapi-codegen/echo-middleware) + + | +
| + +[Fiber](https://github.com/gofiber/fiber) + + | ++ +[fiber-middleware](https://github.com/oapi-codegen/fiber-middleware) + + | + +
| + +[Gin](https://github.com/gin-gonic/gin) + + | ++ +[gin-middleware](https://github.com/oapi-codegen/gin-middleware) + + | +
| + +[gorilla/mux](https://github.com/gorilla/mux) + + | ++ +[nethttp-middleware](https://github.com/oapi-codegen/nethttp-middleware) + + | + +
| + +[Iris](https://github.com/kataras/iris) + + | ++ +[iris-middleware](https://github.com/oapi-codegen/iris-middleware) + + | + +
| + +[1.22+ `net/http`](https://pkg.go.dev/net/http) + + | ++ +[nethttp-middleware](https://github.com/oapi-codegen/nethttp-middleware) + + | + +
+
+
+
+
+### `additionalProperties` as `integer`s
+
+```yaml
+components:
+ schemas:
+ Thing:
+ type: object
+ required:
+ - id
+ properties:
+ id:
+ type: integer
+ # simple type
+ additionalProperties:
+ type: integer
+```
+
+Will generate:
+
+```go
+// Thing defines model for Thing.
+type Thing struct {
+ Id int `json:"id"`
+ AdditionalProperties map[string]int `json:"-"`
+}
+
+// with generated boilerplate below
+```
+
+Boilerplate
+ +```go + +// Getter for additional properties for Thing. Returns the specified +// element and whether it was found +func (a Thing) Get(fieldName string) (value interface{}, found bool) { + if a.AdditionalProperties != nil { + value, found = a.AdditionalProperties[fieldName] + } + return +} + +// Setter for additional properties for Thing +func (a *Thing) Set(fieldName string, value interface{}) { + if a.AdditionalProperties == nil { + a.AdditionalProperties = make(map[string]interface{}) + } + a.AdditionalProperties[fieldName] = value +} + +// Override default JSON handling for Thing to handle AdditionalProperties +func (a *Thing) UnmarshalJSON(b []byte) error { + object := make(map[string]json.RawMessage) + err := json.Unmarshal(b, &object) + if err != nil { + return err + } + + if raw, found := object["id"]; found { + err = json.Unmarshal(raw, &a.Id) + if err != nil { + return fmt.Errorf("error reading 'id': %w", err) + } + delete(object, "id") + } + + if len(object) != 0 { + a.AdditionalProperties = make(map[string]interface{}) + for fieldName, fieldBuf := range object { + var fieldVal interface{} + err := json.Unmarshal(fieldBuf, &fieldVal) + if err != nil { + return fmt.Errorf("error unmarshaling field %s: %w", fieldName, err) + } + a.AdditionalProperties[fieldName] = fieldVal + } + } + return nil +} + +// Override default JSON handling for Thing to handle AdditionalProperties +func (a Thing) MarshalJSON() ([]byte, error) { + var err error + object := make(map[string]json.RawMessage) + + object["id"], err = json.Marshal(a.Id) + if err != nil { + return nil, fmt.Errorf("error marshaling 'id': %w", err) + } + + for fieldName, field := range a.AdditionalProperties { + object[fieldName], err = json.Marshal(field) + if err != nil { + return nil, fmt.Errorf("error marshaling '%s': %w", fieldName, err) + } + } + return json.Marshal(object) +} +``` + +
+
+
+
+### `additionalProperties` with an object
+
+```yaml
+components:
+ schemas:
+ Thing:
+ type: object
+ required:
+ - id
+ properties:
+ id:
+ type: integer
+ # object
+ additionalProperties:
+ type: object
+ properties:
+ foo:
+ type: string
+```
+
+Will generate:
+
+```go
+// Thing defines model for Thing.
+type Thing struct {
+ Id int `json:"id"`
+ AdditionalProperties map[string]struct {
+ Foo *string `json:"foo,omitempty"`
+ } `json:"-"`
+}
+
+// with generated boilerplate below
+```
+
+Boilerplate
+ +```go +// Getter for additional properties for Thing. Returns the specified +// element and whether it was found +func (a Thing) Get(fieldName string) (value int, found bool) { + if a.AdditionalProperties != nil { + value, found = a.AdditionalProperties[fieldName] + } + return +} + +// Setter for additional properties for Thing +func (a *Thing) Set(fieldName string, value int) { + if a.AdditionalProperties == nil { + a.AdditionalProperties = make(map[string]int) + } + a.AdditionalProperties[fieldName] = value +} + +// Override default JSON handling for Thing to handle AdditionalProperties +func (a *Thing) UnmarshalJSON(b []byte) error { + object := make(map[string]json.RawMessage) + err := json.Unmarshal(b, &object) + if err != nil { + return err + } + + if raw, found := object["id"]; found { + err = json.Unmarshal(raw, &a.Id) + if err != nil { + return fmt.Errorf("error reading 'id': %w", err) + } + delete(object, "id") + } + + if len(object) != 0 { + a.AdditionalProperties = make(map[string]int) + for fieldName, fieldBuf := range object { + var fieldVal int + err := json.Unmarshal(fieldBuf, &fieldVal) + if err != nil { + return fmt.Errorf("error unmarshaling field %s: %w", fieldName, err) + } + a.AdditionalProperties[fieldName] = fieldVal + } + } + return nil +} + +// Override default JSON handling for Thing to handle AdditionalProperties +func (a Thing) MarshalJSON() ([]byte, error) { + var err error + object := make(map[string]json.RawMessage) + + object["id"], err = json.Marshal(a.Id) + if err != nil { + return nil, fmt.Errorf("error marshaling 'id': %w", err) + } + + for fieldName, field := range a.AdditionalProperties { + object[fieldName], err = json.Marshal(field) + if err != nil { + return nil, fmt.Errorf("error marshaling '%s': %w", fieldName, err) + } + } + return json.Marshal(object) +} +``` + +
+
+
+
+## Changing the names of generated types
+
+As of `oapi-codegen` v2.2.0, it is now possible to use the `output-options` configuration's `name-normalizer` to define the logic for how to convert an OpenAPI name (i.e. an Operation ID or a Schema name) and construct a Go type name.
+
+Boilerplate
+ +```go +// Getter for additional properties for Thing. Returns the specified +// element and whether it was found +func (a Thing) Get(fieldName string) (value struct { + Foo *string `json:"foo,omitempty"` +}, found bool) { + if a.AdditionalProperties != nil { + value, found = a.AdditionalProperties[fieldName] + } + return +} + +// Setter for additional properties for Thing +func (a *Thing) Set(fieldName string, value struct { + Foo *string `json:"foo,omitempty"` +}) { + if a.AdditionalProperties == nil { + a.AdditionalProperties = make(map[string]struct { + Foo *string `json:"foo,omitempty"` + }) + } + a.AdditionalProperties[fieldName] = value +} + +// Override default JSON handling for Thing to handle AdditionalProperties +func (a *Thing) UnmarshalJSON(b []byte) error { + object := make(map[string]json.RawMessage) + err := json.Unmarshal(b, &object) + if err != nil { + return err + } + + if raw, found := object["id"]; found { + err = json.Unmarshal(raw, &a.Id) + if err != nil { + return fmt.Errorf("error reading 'id': %w", err) + } + delete(object, "id") + } + + if len(object) != 0 { + a.AdditionalProperties = make(map[string]struct { + Foo *string `json:"foo,omitempty"` + }) + for fieldName, fieldBuf := range object { + var fieldVal struct { + Foo *string `json:"foo,omitempty"` + } + err := json.Unmarshal(fieldBuf, &fieldVal) + if err != nil { + return fmt.Errorf("error unmarshaling field %s: %w", fieldName, err) + } + a.AdditionalProperties[fieldName] = fieldVal + } + } + return nil +} + +// Override default JSON handling for Thing to handle AdditionalProperties +func (a Thing) MarshalJSON() ([]byte, error) { + var err error + object := make(map[string]json.RawMessage) + + object["id"], err = json.Marshal(a.Id) + if err != nil { + return nil, fmt.Errorf("error marshaling 'id': %w", err) + } + + for fieldName, field := range a.AdditionalProperties { + object[fieldName], err = json.Marshal(field) + if err != nil { + return nil, fmt.Errorf("error marshaling '%s': %w", fieldName, err) + } + } + return json.Marshal(object) +} +``` + +
+
+
+
+Example, using default configuration
+ +By default, `oapi-codegen` will perform camel-case conversion, so for a spec such as: + +```yaml +openapi: "3.0.0" +info: + version: 1.0.0 + title: Example code for the `name-normalizer` output option +paths: + /api/pets/{petId}: + get: + summary: Get pet given identifier. + operationId: getHttpPet + parameters: + - name: petId + in: path + required: true + schema: + type: string + responses: + '200': + description: valid pet + content: + application/json: + schema: + $ref: '#/components/schemas/Pet' +components: + schemas: + Pet: + type: object + required: + - uuid + - name + properties: + uuid: + type: string + description: The pet uuid. + name: + type: string + description: The name of the pet. + Error: + required: + - code + - message + properties: + code: + type: integer + format: int32 + description: Error code + message: + type: string + description: Error message + OneOf2things: + description: "Notice that the `things` is not capitalised" + oneOf: + - type: object + required: + - id + properties: + id: + type: integer + - type: object + required: + - id + properties: + id: + type: string + format: uuid +``` + +This will produce: + +```go +// OneOf2things Notice that the `things` is not capitalised +type OneOf2things struct { + union json.RawMessage +} + +// Pet defines model for Pet. +type Pet struct { + // Name The name of the pet. + Name string `json:"name"` + + // Uuid The pet uuid. + Uuid string `json:"uuid"` +} + +// The interface specification for the client above. +type ClientInterface interface { + // GetHttpPet request + GetHttpPet(ctx context.Context, petId string, reqEditors ...RequestEditorFn) (*http.Response, error) +} +``` + +
+
+Example, using
+
+By default, `oapi-codegen` will perform camel-case conversion, so for a spec such as:
+
+```yaml
+openapi: "3.0.0"
+info:
+ version: 1.0.0
+ title: Example code for the `name-normalizer` output option
+paths:
+ /api/pets/{petId}:
+ get:
+ summary: Get pet given identifier.
+ operationId: getHttpPet
+ parameters:
+ - name: petId
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: valid pet
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Pet'
+components:
+ schemas:
+ Pet:
+ type: object
+ required:
+ - uuid
+ - name
+ properties:
+ uuid:
+ type: string
+ description: The pet uuid.
+ name:
+ type: string
+ description: The name of the pet.
+ Error:
+ required:
+ - code
+ - message
+ properties:
+ code:
+ type: integer
+ format: int32
+ description: Error code
+ message:
+ type: string
+ description: Error message
+ OneOf2things:
+ description: "Notice that the `things` is not capitalised"
+ oneOf:
+ - type: object
+ required:
+ - id
+ properties:
+ id:
+ type: integer
+ - type: object
+ required:
+ - id
+ properties:
+ id:
+ type: string
+ format: uuid
+```
+
+This will produce:
+
+```go
+// OneOf2things Notice that the `things` is not capitalised
+type OneOf2things struct {
+ union json.RawMessage
+}
+
+// Pet defines model for Pet.
+type Pet struct {
+ // Name The name of the pet.
+ Name string `json:"name"`
+
+ // UUID The pet uuid.
+ UUID string `json:"uuid"`
+}
+
+// The interface specification for the client above.
+type ClientInterface interface {
+ // GetHTTPPet request
+ GetHTTPPet(ctx context.Context, petID string, reqEditors ...RequestEditorFn) (*http.Response, error)
+}
+```
+
+
+
+
+For more details of what the resulting code looks like, check out [the test cases](internal/test/outputoptions/name-normalizer/).
+
+## Examples
+
+The [examples directory](examples) contains some additional cases which are useful examples for how to use `oapi-codegen`, including how you'd take the Petstore API and implement it with `oapi-codegen`.
+
+You could also find some cases of how the project can be used by checking out our [internal test cases](internal/test) which are real-world usages that make up our regression tests.
+
+### Blog posts
+
+We love reading posts by the community about how to use the project.
+
+Here are a few we've found around the Web:
+
+- [Building a Go RESTful API with design-first OpenAPI contracts](https://www.jvt.me/posts/2022/07/12/go-openapi-server/)
+- [A Practical Guide to Using oapi-codegen in Golang API Development with the Fiber Framework](https://medium.com/@fikihalan/a-practical-guide-to-using-oapi-codegen-in-golang-api-development-with-the-fiber-framework-bce2a59380ae)
+- [Generating Go server code from OpenAPI 3 definitions](https://ldej.nl/post/generating-go-from-openapi-3/)
+- [Go Client Code Generation from Swagger and OpenAPI](https://medium.com/@kyodo-tech/go-client-code-generation-from-swagger-and-openapi-a0576831836c)
+- [Go oapi-codegen + request validation](https://blog.commitsmart.com/go-oapi-codegen-request-validation-285398b37dc8)
+
+Got one to add? Please raise a PR!
+
+## Frequently Asked Questions (FAQs)
+
+### How does `oapi-codegen` handle `anyOf`, `allOf` and `oneOf`?
+
+`oapi-codegen` supports `anyOf`, `allOf` and `oneOf` for generated code.
+
+For instance, through the following OpenAPI spec:
+
+```yaml
+openapi: "3.0.0"
+info:
+ version: 1.0.0
+ title: Using complex schemas
+ description: An example of `anyOf`, `allOf` and `oneOf`
+components:
+ schemas:
+ # base types
+ Client:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ Identity:
+ type: object
+ required:
+ - issuer
+ properties:
+ issuer:
+ type: string
+
+ # allOf performs a union of all types defined
+ ClientWithId:
+ allOf:
+ - $ref: '#/components/schemas/Client'
+ - properties:
+ id:
+ type: integer
+ required:
+ - id
+
+ # allOf performs a union of all types defined, but if there's a duplicate field defined, it'll be overwritten by the last schema
+ # https://github.com/deepmap/oapi-codegen/issues/1569
+ IdentityWithDuplicateField:
+ allOf:
+ # `issuer` will be ignored
+ - $ref: '#/components/schemas/Identity'
+ # `issuer` will be ignored
+ - properties:
+ issuer:
+ type: integer
+ # `issuer` will take precedence
+ - properties:
+ issuer:
+ type: object
+ properties:
+ name:
+ type: string
+ required:
+ - name
+
+ # anyOf results in a type that has an `AsClient`/`MergeClient`/`FromClient` and an `AsIdentity`/`MergeIdentity`/`FromIdentity` method so you can choose which of them you want to retrieve
+ ClientAndMaybeIdentity:
+ anyOf:
+ - $ref: '#/components/schemas/Client'
+ - $ref: '#/components/schemas/Identity'
+
+ # oneOf results in a type that has an `AsClient`/`MergeClient`/`FromClient` and an `AsIdentity`/`MergeIdentity`/`FromIdentity` method so you can choose which of them you want to retrieve
+ ClientOrIdentity:
+ oneOf:
+ - $ref: '#/components/schemas/Client'
+ - $ref: '#/components/schemas/Identity'
+```
+
+This results in the following types:
+
+Example, using ToCamelCaseWithInitialisms
+
+By default, `oapi-codegen` will perform camel-case conversion, so for a spec such as:
+
+```yaml
+openapi: "3.0.0"
+info:
+ version: 1.0.0
+ title: Example code for the `name-normalizer` output option
+paths:
+ /api/pets/{petId}:
+ get:
+ summary: Get pet given identifier.
+ operationId: getHttpPet
+ parameters:
+ - name: petId
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: valid pet
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/Pet'
+components:
+ schemas:
+ Pet:
+ type: object
+ required:
+ - uuid
+ - name
+ properties:
+ uuid:
+ type: string
+ description: The pet uuid.
+ name:
+ type: string
+ description: The name of the pet.
+ Error:
+ required:
+ - code
+ - message
+ properties:
+ code:
+ type: integer
+ format: int32
+ description: Error code
+ message:
+ type: string
+ description: Error message
+ OneOf2things:
+ description: "Notice that the `things` is not capitalised"
+ oneOf:
+ - type: object
+ required:
+ - id
+ properties:
+ id:
+ type: integer
+ - type: object
+ required:
+ - id
+ properties:
+ id:
+ type: string
+ format: uuid
+```
+
+This will produce:
+
+```go
+// OneOf2things Notice that the `things` is not capitalised
+type OneOf2things struct {
+ union json.RawMessage
+}
+
+// Pet defines model for Pet.
+type Pet struct {
+ // Name The name of the pet.
+ Name string `json:"name"`
+
+ // UUID The pet uuid.
+ UUID string `json:"uuid"`
+}
+
+// The interface specification for the client above.
+type ClientInterface interface {
+ // GetHTTPPet request
+ GetHTTPPet(ctx context.Context, petID string, reqEditors ...RequestEditorFn) (*http.Response, error)
+}
+```
+
+
+
+
+
+Base types
+ +```go +// Client defines model for Client. +type Client struct { + Name string `json:"name"` +} + +// Identity defines model for Identity. +type Identity struct { + Issuer string `json:"issuer"` +} +``` + +
+
+
+
+```go
+// ClientWithId defines model for ClientWithId.
+type ClientWithId struct {
+ Id int `json:"id"`
+ Name string `json:"name"`
+}
+
+// IdentityWithDuplicateField defines model for IdentityWithDuplicateField.
+type IdentityWithDuplicateField struct {
+ Issuer struct {
+ Name string `json:"name"`
+ } `json:"issuer"`
+}
+```
+
+
+
+allOf
+
+```go
+// ClientWithId defines model for ClientWithId.
+type ClientWithId struct {
+ Id int `json:"id"`
+ Name string `json:"name"`
+}
+
+// IdentityWithDuplicateField defines model for IdentityWithDuplicateField.
+type IdentityWithDuplicateField struct {
+ Issuer struct {
+ Name string `json:"name"`
+ } `json:"issuer"`
+}
+```
+
+
+
+
+
+```go
+import (
+ "encoding/json"
+
+ "github.com/oapi-codegen/runtime"
+)
+
+// ClientAndMaybeIdentity defines model for ClientAndMaybeIdentity.
+type ClientAndMaybeIdentity struct {
+ union json.RawMessage
+}
+
+// AsClient returns the union data inside the ClientAndMaybeIdentity as a Client
+func (t ClientAndMaybeIdentity) AsClient() (Client, error) {
+ var body Client
+ err := json.Unmarshal(t.union, &body)
+ return body, err
+}
+
+// FromClient overwrites any union data inside the ClientAndMaybeIdentity as the provided Client
+func (t *ClientAndMaybeIdentity) FromClient(v Client) error {
+ b, err := json.Marshal(v)
+ t.union = b
+ return err
+}
+
+// MergeClient performs a merge with any union data inside the ClientAndMaybeIdentity, using the provided Client
+func (t *ClientAndMaybeIdentity) MergeClient(v Client) error {
+ b, err := json.Marshal(v)
+ if err != nil {
+ return err
+ }
+
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ return err
+}
+
+// AsIdentity returns the union data inside the ClientAndMaybeIdentity as a Identity
+func (t ClientAndMaybeIdentity) AsIdentity() (Identity, error) {
+ var body Identity
+ err := json.Unmarshal(t.union, &body)
+ return body, err
+}
+
+// FromIdentity overwrites any union data inside the ClientAndMaybeIdentity as the provided Identity
+func (t *ClientAndMaybeIdentity) FromIdentity(v Identity) error {
+ b, err := json.Marshal(v)
+ t.union = b
+ return err
+}
+
+// MergeIdentity performs a merge with any union data inside the ClientAndMaybeIdentity, using the provided Identity
+func (t *ClientAndMaybeIdentity) MergeIdentity(v Identity) error {
+ b, err := json.Marshal(v)
+ if err != nil {
+ return err
+ }
+
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ return err
+}
+
+func (t ClientAndMaybeIdentity) MarshalJSON() ([]byte, error) {
+ b, err := t.union.MarshalJSON()
+ return b, err
+}
+
+func (t *ClientAndMaybeIdentity) UnmarshalJSON(b []byte) error {
+ err := t.union.UnmarshalJSON(b)
+ return err
+}
+
+
+```
+
+
+
+anyOf
+
+```go
+import (
+ "encoding/json"
+
+ "github.com/oapi-codegen/runtime"
+)
+
+// ClientAndMaybeIdentity defines model for ClientAndMaybeIdentity.
+type ClientAndMaybeIdentity struct {
+ union json.RawMessage
+}
+
+// AsClient returns the union data inside the ClientAndMaybeIdentity as a Client
+func (t ClientAndMaybeIdentity) AsClient() (Client, error) {
+ var body Client
+ err := json.Unmarshal(t.union, &body)
+ return body, err
+}
+
+// FromClient overwrites any union data inside the ClientAndMaybeIdentity as the provided Client
+func (t *ClientAndMaybeIdentity) FromClient(v Client) error {
+ b, err := json.Marshal(v)
+ t.union = b
+ return err
+}
+
+// MergeClient performs a merge with any union data inside the ClientAndMaybeIdentity, using the provided Client
+func (t *ClientAndMaybeIdentity) MergeClient(v Client) error {
+ b, err := json.Marshal(v)
+ if err != nil {
+ return err
+ }
+
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ return err
+}
+
+// AsIdentity returns the union data inside the ClientAndMaybeIdentity as a Identity
+func (t ClientAndMaybeIdentity) AsIdentity() (Identity, error) {
+ var body Identity
+ err := json.Unmarshal(t.union, &body)
+ return body, err
+}
+
+// FromIdentity overwrites any union data inside the ClientAndMaybeIdentity as the provided Identity
+func (t *ClientAndMaybeIdentity) FromIdentity(v Identity) error {
+ b, err := json.Marshal(v)
+ t.union = b
+ return err
+}
+
+// MergeIdentity performs a merge with any union data inside the ClientAndMaybeIdentity, using the provided Identity
+func (t *ClientAndMaybeIdentity) MergeIdentity(v Identity) error {
+ b, err := json.Marshal(v)
+ if err != nil {
+ return err
+ }
+
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ return err
+}
+
+func (t ClientAndMaybeIdentity) MarshalJSON() ([]byte, error) {
+ b, err := t.union.MarshalJSON()
+ return b, err
+}
+
+func (t *ClientAndMaybeIdentity) UnmarshalJSON(b []byte) error {
+ err := t.union.UnmarshalJSON(b)
+ return err
+}
+
+
+```
+
+
+
+
+
+```go
+// AsClient returns the union data inside the ClientOrIdentity as a Client
+func (t ClientOrIdentity) AsClient() (Client, error) {
+ var body Client
+ err := json.Unmarshal(t.union, &body)
+ return body, err
+}
+
+// FromClient overwrites any union data inside the ClientOrIdentity as the provided Client
+func (t *ClientOrIdentity) FromClient(v Client) error {
+ b, err := json.Marshal(v)
+ t.union = b
+ return err
+}
+
+// MergeClient performs a merge with any union data inside the ClientOrIdentity, using the provided Client
+func (t *ClientOrIdentity) MergeClient(v Client) error {
+ b, err := json.Marshal(v)
+ if err != nil {
+ return err
+ }
+
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ return err
+}
+
+// AsIdentity returns the union data inside the ClientOrIdentity as a Identity
+func (t ClientOrIdentity) AsIdentity() (Identity, error) {
+ var body Identity
+ err := json.Unmarshal(t.union, &body)
+ return body, err
+}
+
+// FromIdentity overwrites any union data inside the ClientOrIdentity as the provided Identity
+func (t *ClientOrIdentity) FromIdentity(v Identity) error {
+ b, err := json.Marshal(v)
+ t.union = b
+ return err
+}
+
+// MergeIdentity performs a merge with any union data inside the ClientOrIdentity, using the provided Identity
+func (t *ClientOrIdentity) MergeIdentity(v Identity) error {
+ b, err := json.Marshal(v)
+ if err != nil {
+ return err
+ }
+
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ return err
+}
+
+func (t ClientOrIdentity) MarshalJSON() ([]byte, error) {
+ b, err := t.union.MarshalJSON()
+ return b, err
+}
+
+func (t *ClientOrIdentity) UnmarshalJSON(b []byte) error {
+ err := t.union.UnmarshalJSON(b)
+ return err
+}
+```
+
+
+
+For more info, check out [the example code](examples/anyof-allof-oneof/).
+
+### How can I ignore parts of the spec I don't care about?
+
+By default, `oapi-codegen` will generate everything from the specification.
+
+If you'd like to reduce what's generated, you can use one of a few options in [the configuration file](#usage) to tune the generation of the resulting output:
+
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/deepmap/oapi-codegen/HEAD/configuration-schema.json
+output-options:
+ include-tags: []
+ exclude-tags: []
+ include-operation-ids: []
+ exclude-operation-ids: []
+ exclude-schemas: []
+```
+
+Check [the docs](https://pkg.go.dev/github.com/oapi-codegen/oapi-codegen/v2/pkg/codegen#OutputOptions) for more details of usage.
+
+### Should I commit the generated code?
+
+We recommend doing so, yes, for the following reasons:
+
+- It means it's easier to view the impact of a change - be it due to an upgrade of `oapi-codegen`, or a change to your spec - and has helped catch (possibly) breaking changes in the past more easily
+- It then allows your codebase to be consumed as a library, as all the files are committed
+
+This means you'll need to have your CI/CD pipeline validate that generated files are all up-to-date, but that's a fairly straightforward piece of work.
+
+### Should I lint the generated code?
+
+We really ask that you don't. Although it intends to be idiomatic Go code, it's not expected to pass all the various linting rules that your project may apply.
+
+> [!NOTE]
+> We will, on occasion, improve the generated code to fix some linting warnings, such as those from `go vet`, but this should not be an expected change.
+
+### I've just updated my version of `kin-openapi`, and now I can't build my code 😠
+
+The [kin-openapi](https://github.com/getkin/kin-openapi) project - which we 💜 for providing a great library and set of tooling for interacting with OpenAPI - is a pre-v1 release, which means that they're within their rights to push breaking changes.
+
+This may lead to breakage in your consuming code, and if so, sorry that's happened!
+
+We'll be aware of the issue, and will work to update both the core `oapi-codegen` and the middlewares accordingly.
+
+## Sponsors
+
+For the most part, `oapi-codegen` is maintained in two busy peoples' free time. As noted in [Creating a more sustainable model for `oapi-codegen` in the future](https://github.com/deepmap/oapi-codegen/discussions/1606), we're looking to make this a more sustainable project in the future.
+
+We're very appreciative of [the many contributors over the years](https://github.com/deepmap/oapi-codegen/graphs/contributors) and the ongoing use of the project 💜
+
+Please consider sponsoring us through GitHub Sponsors either [on the organisation](https://github.com/sponsors/oapi-codegen/) or [directly for Jamie](https://github.com/sponsors/jamietanna/), which helps work towards us being able to maintain the project long term.
+
+See [this blog post from Tidelift](https://blog.tidelift.com/paying-maintainers-the-howto) for more details on how to talk to your company about sponsoring maintainers of (Open Source) projects you depend on.
+
+We are currently generously sponsored by the following folks, each of whom provide sponsorship for 1 hour of work a month:
+
+oneOf
+
+```go
+// AsClient returns the union data inside the ClientOrIdentity as a Client
+func (t ClientOrIdentity) AsClient() (Client, error) {
+ var body Client
+ err := json.Unmarshal(t.union, &body)
+ return body, err
+}
+
+// FromClient overwrites any union data inside the ClientOrIdentity as the provided Client
+func (t *ClientOrIdentity) FromClient(v Client) error {
+ b, err := json.Marshal(v)
+ t.union = b
+ return err
+}
+
+// MergeClient performs a merge with any union data inside the ClientOrIdentity, using the provided Client
+func (t *ClientOrIdentity) MergeClient(v Client) error {
+ b, err := json.Marshal(v)
+ if err != nil {
+ return err
+ }
+
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ return err
+}
+
+// AsIdentity returns the union data inside the ClientOrIdentity as a Identity
+func (t ClientOrIdentity) AsIdentity() (Identity, error) {
+ var body Identity
+ err := json.Unmarshal(t.union, &body)
+ return body, err
+}
+
+// FromIdentity overwrites any union data inside the ClientOrIdentity as the provided Identity
+func (t *ClientOrIdentity) FromIdentity(v Identity) error {
+ b, err := json.Marshal(v)
+ t.union = b
+ return err
+}
+
+// MergeIdentity performs a merge with any union data inside the ClientOrIdentity, using the provided Identity
+func (t *ClientOrIdentity) MergeIdentity(v Identity) error {
+ b, err := json.Marshal(v)
+ if err != nil {
+ return err
+ }
+
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ return err
+}
+
+func (t ClientOrIdentity) MarshalJSON() ([]byte, error) {
+ b, err := t.union.MarshalJSON()
+ return b, err
+}
+
+func (t *ClientOrIdentity) UnmarshalJSON(b []byte) error {
+ err := t.union.UnmarshalJSON(b)
+ return err
+}
+```
+
+
+
+ 
+