| +Extension + | ++Description + | +
|---|---|
|
+
+`x-go-type` +`x-go-type-import` + + |
++Override the generated type definition (and optionally, add an import from another package) + | +
| + +`x-go-type-skip-optional-pointer` + + | ++Do not add a pointer type for optional fields in structs + | +
| + +`x-go-name` + + | ++Override the generated name of a field or a type + | +
| + +`x-go-type-name` + + | ++Override the generated name of a type + | +
| + +`x-omitempty` + + | ++Force the presence of the JSON tag `omitempty` on a field + | +
| + +`x-omitzero` + + | ++Force the presence of the JSON tag `omitzero` on a field + | +
| + +`x-go-json-ignore` + + | ++When (un)marshaling JSON, ignore field(s) + | +
| + +`x-oapi-codegen-extra-tags` + + | ++Generate arbitrary struct tags to fields + | +
| + +`x-enum-varnames` / `x-enumNames` + + | ++Override generated variable names for enum constants + | +
| + +`x-deprecated-reason` + + | ++Add a GoDoc deprecation warning to a type + | +
| + +`x-order` + + | ++Explicitly order struct fields + | +
| + +`x-oapi-codegen-only-honour-go-name` + + | ++Only honour the `x-go-name` when generating field names + | +
| +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) + + | + +
| + +Any other server (which conforms to `net/http`) + + | ++ +[nethttp-middleware](https://github.com/oapi-codegen/nethttp-middleware) + + | + +
-Remaining arguments can be passed in headers, query arguments or cookies. Those
-will be written to a `params` object. Look at the `FindPets` function above, it
-takes as input `FindPetsParams`, which is defined as follows:
+
-There are a few ways of registering your http handler based on the type of server generated i.e. `-generate server` or `-generate chi-server`
-Boilerplate
```go -// Parameters object for FindPets -type FindPetsParams struct { - Tags *[]string `json:"tags,omitempty"` - Limit *int32 `json:"limit,omitempty"` + +// 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 } -``` -The HTTP query parameter `limit` turns into a Go field named `Limit`. It is -passed by pointer, since it is an optional parameter. If the parameter is -specified, the pointer will be non-`nil`, and you can read its value. +// 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 +} -If you changed the OpenAPI specification to make the parameter required, the -`FindPetsParams` structure will contain the type by 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 + } -```go -type FindPetsParams struct { - Tags *[]string `json:"tags,omitempty"` - Limit int32 `json:"limit"` + 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) } ``` -### Registering handlers +Echo
+### `additionalProperties` as `integer`s
-Code generated using `-generate server`.
+```yaml
+components:
+ schemas:
+ Thing:
+ type: object
+ required:
+ - id
+ properties:
+ id:
+ type: integer
+ # simple type
+ additionalProperties:
+ type: integer
+```
-The usage of `Echo` is out of scope of this doc, but once you have an
-echo instance, we generate a utility function to help you associate your handlers
-with this autogenerated code. For the pet store, it looks like this:
+Will generate:
```go
-func RegisterHandlers(router codegen.EchoRouter, si ServerInterface) {
- wrapper := ServerInterfaceWrapper{
- Handler: si,
- }
- router.GET("/pets", wrapper.FindPets)
- router.POST("/pets", wrapper.AddPet)
- router.DELETE("/pets/:id", wrapper.DeletePet)
- router.GET("/pets/:id", wrapper.FindPetById)
+// Thing defines model for Thing.
+type Thing struct {
+ Id int `json:"id"`
+ AdditionalProperties map[string]int `json:"-"`
}
+
+// with generated boilerplate below
```
-The wrapper functions referenced above contain generated code which pulls
-parameters off the `Echo` request context, and unmarshals them into Go objects.
+
-You would register the generated handlers as follows:
+
+// 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
+}
-Boilerplate
```go -func SetupHandler() { - var myApi PetStoreImpl // This implements the pet store interface - e := echo.New() - petstore.RegisterHandlers(e, &myApi) - ... +// 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 } -``` -Chi
+// 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
+ }
-Code generated using `-generate chi-server`.
+ 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")
+ }
-```go
-type PetStoreImpl struct {}
-func (*PetStoreImpl) GetPets(w http.ResponseWriter, r *http.Request) {
- // Implement me
+ 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
}
-func SetupHandler() {
- var myApi PetStoreImpl
+// Override default JSON handling for Thing to handle AdditionalProperties
+func (a Thing) MarshalJSON() ([]byte, error) {
+ var err error
+ object := make(map[string]json.RawMessage)
- r := chi.NewRouter()
- r.Mount("/", Handler(&myApi))
+ 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)
}
```
-Gin
+### `additionalProperties` with an object
-Code generated using `-generate gin`.
+```yaml
+components:
+ schemas:
+ Thing:
+ type: object
+ required:
+ - id
+ properties:
+ id:
+ type: integer
+ # object
+ additionalProperties:
+ type: object
+ properties:
+ foo:
+ type: string
+```
-The usage of `gin` is out of scope of this doc, but once you have an
-gin instance, we generate a utility function to help you associate your handlers
-with this autogenerated code. For the pet store, it looks like this:
+Will generate:
```go
-// RegisterHandlersWithOptions creates http.Handler with additional options
-func RegisterHandlersWithOptions(router *gin.Engine, si ServerInterface, options GinServerOptions) *gin.Engine {
- wrapper := ServerInterfaceWrapper{
- Handler: si,
- HandlerMiddlewares: options.Middlewares,
- }
-
- router.GET(options.BaseURL+"/pets", wrapper.FindPets)
- router.POST(options.BaseURL+"/pets", wrapper.AddPet)
- router.DELETE(options.BaseURL+"/pets/:id", wrapper.DeletePet)
- router.GET(options.BaseURL+"/pets/:id", wrapper.FindPetByID)
- return router
+// Thing defines model for Thing.
+type Thing struct {
+ Id int `json:"id"`
+ AdditionalProperties map[string]struct {
+ Foo *string `json:"foo,omitempty"`
+ } `json:"-"`
}
-```
-```go
-import (
- "github.com/gin-gonic/gin"
- "github.com/deepmap/oapi-codegen/examples/petstore-expanded/gin/api"
- middleware "github.com/oapi-codegen/gin-middleware"
-)
+// with generated boilerplate below
+```
-type PetStoreImpl struct {}
-func (*PetStoreImpl) GetPets(w http.ResponseWriter, r *http.Request) {
- // Implement me
-}
+
-func SetupHandler() {
- var myApi PetStoreImpl
+
+// 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
+}
-Boilerplate
- r := gin.Default() - r.Use(middleware.OapiRequestValidator(swagger)) - r = api.RegisterHandlers(r, petStore) +```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 } -``` -net/http
+// 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
+ }
-[Chi](https://github.com/go-chi/chi) is 100% compatible with `net/http` allowing the following with code generated using `-generate chi-server`.
+ 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")
+ }
-```go
-type PetStoreImpl struct {}
-func (*PetStoreImpl) GetPets(w http.ResponseWriter, r *http.Request) {
- // Implement me
+ 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
}
-func SetupHandler() {
- var myApi PetStoreImpl
+// 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)
+ }
- http.Handle("/", Handler(&myApi))
+ 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)
}
```
-Alternatively, [Gorilla](https://github.com/gorilla/mux) is also 100% compatible with `net/http` and can be generated with `-generate gorilla`.
+Iris
+One of the key things `oapi-codegen` does is to use an "optional pointer", following idiomatic Go practices, to indicate that a field/type is optional.
-Code generated using `-generate iris`.
+This can be tuned on a per-field basis, using the [`x-go-type-skip-optional-pointer` extension](#ext-x-go-type-skip-optional-pointer), but it can be a bit repetitive, or can be more complex when using an OpenAPI Overlay.
-The usage of `iris` is out of scope of this doc, but once you have an
-gin instance, we generate a utility function to help you associate your handlers
-with this autogenerated code. For the pet store, it looks like this:
+As of `oapi-codegen` v2.5.0, this can be tuned in two specific ways, via the following `output-options:`:
-```go
-// RegisterHandlersWithOptions creates http.Handler with additional options
-func RegisterHandlersWithOptions(router *iris.Application, si ServerInterface, options IrisServerOptions) {
+- `prefer-skip-optional-pointer`: a global default that you do _not_ want the "optional pointer" generated. Optional fields will not have an "optional pointer", and will have an `omitempty` JSON tag
+- `prefer-skip-optional-pointer-with-omitzero`: when used in conjunction with `prefer-skip-optional-pointer`, any optional fields are generated with an `omitzero` JSON tag. **Requires Go 1.24+**
- wrapper := ServerInterfaceWrapper{
- Handler: si,
- }
+In both cases, there is control on a per-field level to set `x-go-type-skip-optional-pointer: false` or `x-omitzero: false` to undo these to field(s).
- router.Get(options.BaseURL+"/pets", wrapper.FindPets)
- router.Post(options.BaseURL+"/pets", wrapper.AddPet)
- router.Delete(options.BaseURL+"/pets/:id", wrapper.DeletePet)
- router.Get(options.BaseURL+"/pets/:id", wrapper.FindPetByID)
+For example, when combining both options:
- router.Build()
-}
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json
+package: preferskipoptionalpointerwithomitzero
+output: gen.go
+generate:
+ # ...
+output-options:
+ # ...
+ prefer-skip-optional-pointer: true
+ prefer-skip-optional-pointer-with-omitzero: true
```
-```go
-import (
- "github.com/kataras/iris/v12"
- "github.com/deepmap/oapi-codegen/examples/petstore-expanded/iris/api"
- middleware "github.com/oapi-codegen/iris-middleware"
-)
-```
+When we have the following spec:
-The wrapper functions referenced above contain generated code which pulls
-parameters off the `Iris` request context, and unmarshals them into Go objects.
+```yaml
+openapi: "3.0.0"
+info:
+ version: 1.0.0
+ title: prefer-skip-optional-pointer-with-omitzero
+components:
+ schemas:
+ ClientWithExtension:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ description: This field is required, so will never have an optional pointer, nor `omitzero`.
+ type: string
+ id:
+ description: This field is optional, but the `prefer-skip-optional-pointer` Output Option ensures that this should not have an optional pointer. However, it will receive `omitzero`.
+ type: number
+ pointer_id:
+ type: number
+ description: This field should have an optional pointer, as the field-level definition of `x-go-type-skip-optional-pointer` overrides the `prefer-skip-optional-pointer` Output Option. This will also not receive an `omitzero`.
+ # NOTE that this overrides the global preference
+ x-go-type-skip-optional-pointer: false
+ no_omit:
+ type: number
+ description: This field is optional, but the `prefer-skip-optional-pointer` Output Option ensures that this should not have an optional pointer. This will not receive `omitzero`, as the field-level definition of `x-omitzero` overrides the `prefer-skip-optional-pointer-with-omitzero` Output Option.
+ # NOTE that this overrides the global preference
+ x-omitzero: false
+```
-You would register the generated handlers as follows:
+We then generate the following Go code:
```go
-func SetupHandler() {
- var myApi PetStoreImpl
+// ...
- i := iris.Default()
- i.Use(middleware.OapiRequestValidator(swagger))
- api.RegisterHandlers(r, &myApi)
+// ClientWithExtension defines model for ClientWithExtension.
+type ClientWithExtension struct {
+ // Id This field is optional, but the `prefer-skip-optional-pointer` Output Option ensures that this should not have an optional pointer. However, it will receive `omitzero`.
+ Id float32 `json:"id,omitempty,omitzero"`
+
+ // Name This field is required, so will never have an optional pointer, nor `omitzero`.
+ Name string `json:"name"`
+
+ // NoOmit This field is optional, but the `prefer-skip-optional-pointer` Output Option ensures that this should not have an optional pointer. This will not receive `omitzero`, as the field-level definition of `x-omitzero` overrides the `prefer-skip-optional-pointer-with-omitzero` Output Option.
+ NoOmit float32 `json:"no_omit,omitempty"`
+
+ // PointerId This field should have an optional pointer, as the field-level definition of `x-go-type-skip-optional-pointer` overrides the `prefer-skip-optional-pointer` Output Option. This will also not receive an `omitzero`.
+ PointerId *float32 `json:"pointer_id,omitempty"`
}
```
-
-To form a response simply return one of the generated structs with corresponding status code and content type. For example,
-to return a status code 200 JSON response for a AddPet use the `AddPet200JSONResponse` struct which will set the correct
-Content-Type header, status code and will marshal the response data. You can also return an error, that will
-cause an `Internal Server Error` response.
+
-[OpenAPI Schemas](https://swagger.io/specification/#schemaObject) implicitly
-accept `additionalProperties`, meaning that any fields provided, but not explicitly
-defined via properties on the schema are accepted as input, and propagated. When
-unspecified, the `additionalProperties` field is assumed to be `true`.
+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 +``` -Short example: +This will produce: ```go -type PetStoreImpl struct {} -func (*PetStoreImpl) GetPets(ctx context.Context, request GetPetsRequestObject) (GetPetsResponseObject, error) { - var result []Pet - // Implement me - return GetPets200JSONResponse(result), nil +// OneOf2things Notice that the `things` is not capitalised +type OneOf2things struct { + union json.RawMessage } -``` -For a complete example see [`examples/petstore-expanded/strict`](https://github.com/deepmap/oapi-codegen/tree/master/examples/petstore-expanded/strict). +// Pet defines model for Pet. +type Pet struct { + // Name The name of the pet. + Name string `json:"name"` -Code is generated with a configuration flag `generate: strict-server: true` along with any other server (echo, chi, gin and gorilla are supported). -The generated strict wrapper can then be used as an implementation for `ServerInterface`. Setup example: + // Uuid The pet uuid. + Uuid string `json:"uuid"` +} -```go -func SetupHandler() { - var myApi PetStoreImpl - myStrictApiHandler := api.NewStrictHandler(myApi, nil) - e := echo.New() - petstore.RegisterHandlers(e, &myStrictApiHandler) +// The interface specification for the client above. +type ClientInterface interface { + // GetHttpPet request + GetHttpPet(ctx context.Context, petId string, reqEditors ...RequestEditorFn) (*http.Response, error) } ``` -Strict server also has its own middlewares. It can access to both request and response structs, -as well as raw request\response data. It can be used for logging the parsed request\response objects, transforming go errors into response structs, -authorization, etc. Note that middlewares are server-specific. - -#### Additional Properties in type definitions +
-Additional properties are tricky to support in Go with typing, and require
-lots of boilerplate code, so in this library, we assume that `additionalProperties`
-defaults to `false` and we don't generate this boilerplate. If you would like
-an object to accept `additionalProperties`, specify a schema for `additionalProperties`.
+Example, using
-Say we declared `NewPet` above like so:
+By default, `oapi-codegen` will perform camel-case conversion, so for a spec such as:
```yaml
-NewPet:
- required:
- - name
- properties:
- name:
- type: string
- tag:
- type: string
- additionalProperties:
- type: string
+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
```
-The Go code for `NewPet` would now look like this:
+This will produce:
```go
-// NewPet defines model for NewPet.
-type NewPet struct {
- Name string `json:"name"`
- Tag *string `json:"tag,omitempty"`
- AdditionalProperties map[string]string `json:"-"`
+// 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)
}
```
-The additionalProperties, of type `string` become `map[string]string`, which maps
-field names to instances of the `additionalProperties` schema.
+
-```go
-// Getter for additional properties for NewPet. Returns the specified
-// element and whether it was found
-func (a NewPet) Get(fieldName string) (value string, found bool) {...}
-// Setter for additional properties for NewPet
-func (a *NewPet) Set(fieldName string, value string) {...}
+For more details of what the resulting code looks like, check out [the test cases](internal/test/outputoptions/name-normalizer/).
-// Override default JSON handling for NewPet to handle additionalProperties
-func (a *NewPet) UnmarshalJSON(b []byte) error {...}
+## Examples
-// Override default JSON handling for NewPet to handle additionalProperties
-func (a NewPet) MarshalJSON() ([]byte, error) {...}w
-```
+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`.
-There are many special cases for `additionalProperties`, such as having to
-define types for inner fields which themselves support additionalProperties, and
-all of them are tested via the [`internal/test/components`](https://github.com/deepmap/oapi-codegen/tree/master/internal/test/components) schemas and tests. Please
-look through those tests for more usage examples.
+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.
-#### oneOf/anyOf/allOf support
+### Blog posts
-- `oneOf` and `anyOf` are implemented using delayed parsing with the help of `json.RawMessage`.
- The following schema will result in a type that has methods such as `AsCat`, `AsDog`, `FromCat`, `FromDog`, `MergeCat`, `MergeDog`. If the schema also includes a discriminator the generated code will also have methods such as `Discriminator`, `ValueByDiscriminator` and will force discriminator value in `From` methods.
+We love reading posts by the community about how to use the project.
-```yaml
-schema:
- oneOf:
- - $ref: '#/components/schemas/Cat'
- - $ref: '#/components/schemas/Dog'
-```
+Here are a few we've found around the Web:
-- `allOf` is supported, by taking the union of all the fields in all the
- component schemas. This is the most useful of these operations, and is
- commonly used to merge objects with an identifier, as in the
- `petstore-expanded` example.
+- [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)
+- [Streamlining Go + Chi Development: Generating Code from an OpenAPI Spec](https://i4o.dev/blog/oapi-codegen-with-chi-router)
-## Generated Client Boilerplate
+Got one to add? Please raise a PR!
-Once your server is up and running, you probably want to make requests to it. If
-you're going to do those requests from your Go code, we also generate a client
-which is conformant with your schema to help in marshaling objects to JSON. It
-uses the same types and similar function signatures to your request handlers.
+## Frequently Asked Questions (FAQs)
-The interface for the pet store looks like this:
+### Does `oapi-codegen` support OpenAPI 3.1?
-```go
-// The interface specification for the client above.
-type ClientInterface interface {
+No, we don't currently.
- // FindPets request
- FindPets(ctx context.Context, params *FindPetsParams, reqEditors ...RequestEditorFn) (*http.Response, error)
+OpenAPI 3.1 support is [awaiting upstream support](https://github.com/oapi-codegen/oapi-codegen/issues/373).
- // AddPet request with JSON body
- AddPet(ctx context.Context, body NewPet, reqEditors ...RequestEditorFn) (*http.Response, error)
+In the meantime, you could follow [steps from this blog post](https://www.jvt.me/posts/2025/05/04/oapi-codegen-trick-openapi-3-1/) to [use OpenAPI Overlay](#modifying-the-input-openapi-specification-with-openapi-overlay) to "downgrade" the OpenAPI 3.1 spec to OpenAPI 3.0.
- // DeletePet request
- DeletePet(ctx context.Context, id int64, reqEditors ...RequestEditorFn) (*http.Response, error)
+### How does `oapi-codegen` handle `anyOf`, `allOf` and `oneOf`?
- // FindPetById request
- FindPetById(ctx context.Context, id int64, reqEditors ...RequestEditorFn) (*http.Response, error)
-}
+`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/oapi-codegen/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'
```
-A Client object which implements the above interface is also generated:
+This results in the following types:
+
+Example, using ToCamelCaseWithInitialisms
-Say we declared `NewPet` above like so:
+By default, `oapi-codegen` will perform camel-case conversion, so for a spec such as:
```yaml
-NewPet:
- required:
- - name
- properties:
- name:
- type: string
- tag:
- type: string
- additionalProperties:
- type: string
+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
```
-The Go code for `NewPet` would now look like this:
+This will produce:
```go
-// NewPet defines model for NewPet.
-type NewPet struct {
- Name string `json:"name"`
- Tag *string `json:"tag,omitempty"`
- AdditionalProperties map[string]string `json:"-"`
+// 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)
}
```
-The additionalProperties, of type `string` become `map[string]string`, which maps
-field names to instances of the `additionalProperties` schema.
+
+
+
-1. If you have more than one request body type, meaning more than one media
- type, you will have a generic handler of this form:
+Base types
```go -// Client which conforms to the OpenAPI3 specification for this service. +// Client defines model for Client. type Client struct { - // The endpoint of the server conforming to this interface, with scheme, - // https://api.deepmap.com for example. - Server string - - // HTTP client with any customized settings, such as certificate chains. - Client http.Client + Name string `json:"name"` +} - // A callback for modifying requests which are generated before sending over - // the network. - RequestEditors []func(ctx context.Context, req *http.Request) error +// Identity defines model for Identity. +type Identity struct { + Issuer string `json:"issuer"` } ``` -Each operation in your OpenAPI spec will result in a client function which -takes the same arguments. It's difficult to handle any arbitrary body that -Swagger supports, so we've done some special casing for bodies, and you may get -more than one function for an operation with a request body. +
- AddPet(ctx context.Context, contentType string, body io.Reader)
+
-2. If you have only a JSON request body, you will get:
+```go
+// ClientWithId defines model for ClientWithId.
+type ClientWithId struct {
+ Id int `json:"id"`
+ Name string `json:"name"`
+}
- AddPet(ctx context.Context, body NewPet)
+// IdentityWithDuplicateField defines model for IdentityWithDuplicateField.
+type IdentityWithDuplicateField struct {
+ Issuer struct {
+ Name string `json:"name"`
+ } `json:"issuer"`
+}
+```
-3. If you have multiple request body types, which include a JSON type you will
- get two functions. We've chosen to give the JSON version a shorter name, as
- we work with JSON and don't want to wear out our keyboards.
+
- AddPet(ctx context.Context, body NewPet)
- AddPetWithBody(ctx context.Context, contentType string, body io.Reader)
+allOf
-2. If you have only a JSON request body, you will get:
+```go
+// ClientWithId defines model for ClientWithId.
+type ClientWithId struct {
+ Id int `json:"id"`
+ Name string `json:"name"`
+}
- AddPet(ctx context.Context, body NewPet)
+// IdentityWithDuplicateField defines model for IdentityWithDuplicateField.
+type IdentityWithDuplicateField struct {
+ Issuer struct {
+ Name string `json:"name"`
+ } `json:"issuer"`
+}
+```
-3. If you have multiple request body types, which include a JSON type you will
- get two functions. We've chosen to give the JSON version a shorter name, as
- we work with JSON and don't want to wear out our keyboards.
+
-The Client object above is fairly flexible, since you can pass in your own
-`http.Client` and a request editing callback. You can use that callback to add
-headers. In our middleware stack, we annotate the context with additional
-information such as the request ID and function tracing information, and we
-use the callback to propagate that information into the request headers. Still, we
-can't foresee all possible usages, so those functions call through to helper
-functions which create requests. In the case of the pet store, we have:
+
```go
-// Request generator for FindPets
-func NewFindPetsRequest(server string, params *FindPetsParams) (*http.Request, error) {...}
-
-// Request generator for AddPet with JSON body
-func NewAddPetRequest(server string, body NewPet) (*http.Request, error) {...}
-
-// Request generator for AddPet with non-JSON body
-func NewAddPetRequestWithBody(server string, contentType string, body io.Reader) (*http.Request, error) {...}
-
-// Request generator for DeletePet
-func NewDeletePetRequest(server string, id int64) (*http.Request, error) {...}
+import (
+ "encoding/json"
-// Request generator for FindPetById
-func NewFindPetByIdRequest(server string, id int64) (*http.Request, error) {...}
-```
+ "github.com/oapi-codegen/runtime"
+)
-You can call these functions to build an `http.Request` from Go objects, which
-will correspond to your request schema. They map one-to-one to the functions on
-the client, except that we always generate the generic non-JSON body handler.
+// ClientAndMaybeIdentity defines model for ClientAndMaybeIdentity.
+type ClientAndMaybeIdentity struct {
+ union json.RawMessage
+}
-There are some caveats to using this code.
+// 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
+}
-- exploded, form style query arguments, which are the default argument format
- in OpenAPI 3.0 are undecidable. Say that I have two objects, one composed of
- the fields `(name=bob, id=5)` and another which has `(name=shoe, color=brown)`.
- The first parameter is named `person` and the second is named `item`. The
- default marshaling style for query args would result in
- `/path/?name=bob,id=5&name=shoe,color=brown`. In order to tell what belongs
- to which object, we'd have to look at all the parameters and try to deduce it,
- but we're lazy, so we didn't. Don't use exploded form style arguments if
- you're passing around objects which have similar field names. If you
- used unexploded form parameters, you'd have
- `/path/?person=name,bob,id,5&item=name,shoe,color,brown`, which an be
- parsed unambiguously.
+// 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
+}
-- Parameters can be defined via `schema` or via `content`. Use the `content` form
- for anything other than trivial objects, they can marshal to arbitrary JSON
- structures. When you send them as cookie (`in: cookie`) arguments, we will
- URL encode them, since JSON delimiters aren't allowed in cookies.
+// 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
+ }
-## Using SecurityProviders
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ return err
+}
-If you generate client-code, you can use some default-provided security providers
-which help you to use the various OpenAPI 3 Authentication mechanism.
+// 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
+}
-```go
- import (
- "github.com/deepmap/oapi-codegen/pkg/securityprovider"
- )
+// 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
+}
- func CreateSampleProviders() error {
- // Example BasicAuth
- // See: https://swagger.io/docs/specification/authentication/basic-authentication/
- basicAuthProvider, basicAuthProviderErr := securityprovider.NewSecurityProviderBasicAuth("MY_USER", "MY_PASS")
- if basicAuthProviderErr != nil {
- panic(basicAuthProviderErr)
- }
+// 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
+ }
- // Example BearerToken
- // See: https://swagger.io/docs/specification/authentication/bearer-authentication/
- bearerTokenProvider, bearerTokenProviderErr := securityprovider.NewSecurityProviderBearerToken("MY_TOKEN")
- if bearerTokenProviderErr != nil {
- panic(bearerTokenProviderErr)
- }
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ return err
+}
- // Example ApiKey provider
- // See: https://swagger.io/docs/specification/authentication/api-keys/
- apiKeyProvider, apiKeyProviderErr := securityprovider.NewSecurityProviderApiKey("query", "myApiKeyParam", "MY_API_KEY")
- if apiKeyProviderErr != nil {
- panic(apiKeyProviderErr)
- }
+func (t ClientAndMaybeIdentity) MarshalJSON() ([]byte, error) {
+ b, err := t.union.MarshalJSON()
+ return b, err
+}
- // Example providing your own provider using an anonymous function wrapping in the
- // InterceptoFn adapter. The behaviour between the InterceptorFn and the Interceptor interface
- // are the same as http.HandlerFunc and http.Handler.
- customProvider := func(req *http.Request, ctx context.Context) error {
- // Just log the request header, nothing else.
- log.Println(req.Header)
- return nil
- }
+func (t *ClientAndMaybeIdentity) UnmarshalJSON(b []byte) error {
+ err := t.union.UnmarshalJSON(b)
+ return err
+}
- // Exhaustive list of some defaults you can use to initialize a Client.
- // If you need to override the underlying httpClient, you can use the option
- //
- // WithHTTPClient(httpClient *http.Client)
- //
- client, clientErr := NewClient("https://api.deepmap.com", WithRequestEditorFn(apiKeyProvider.Intercept))
- return nil
- }
```
-## Extensions
+
-`oapi-codegen` supports the following extended properties:
+anyOf
```go
-// Request generator for FindPets
-func NewFindPetsRequest(server string, params *FindPetsParams) (*http.Request, error) {...}
-
-// Request generator for AddPet with JSON body
-func NewAddPetRequest(server string, body NewPet) (*http.Request, error) {...}
-
-// Request generator for AddPet with non-JSON body
-func NewAddPetRequestWithBody(server string, contentType string, body io.Reader) (*http.Request, error) {...}
-
-// Request generator for DeletePet
-func NewDeletePetRequest(server string, id int64) (*http.Request, error) {...}
+import (
+ "encoding/json"
-// Request generator for FindPetById
-func NewFindPetByIdRequest(server string, id int64) (*http.Request, error) {...}
-```
+ "github.com/oapi-codegen/runtime"
+)
-You can call these functions to build an `http.Request` from Go objects, which
-will correspond to your request schema. They map one-to-one to the functions on
-the client, except that we always generate the generic non-JSON body handler.
+// ClientAndMaybeIdentity defines model for ClientAndMaybeIdentity.
+type ClientAndMaybeIdentity struct {
+ union json.RawMessage
+}
-There are some caveats to using this code.
+// 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
+}
-- exploded, form style query arguments, which are the default argument format
- in OpenAPI 3.0 are undecidable. Say that I have two objects, one composed of
- the fields `(name=bob, id=5)` and another which has `(name=shoe, color=brown)`.
- The first parameter is named `person` and the second is named `item`. The
- default marshaling style for query args would result in
- `/path/?name=bob,id=5&name=shoe,color=brown`. In order to tell what belongs
- to which object, we'd have to look at all the parameters and try to deduce it,
- but we're lazy, so we didn't. Don't use exploded form style arguments if
- you're passing around objects which have similar field names. If you
- used unexploded form parameters, you'd have
- `/path/?person=name,bob,id,5&item=name,shoe,color,brown`, which an be
- parsed unambiguously.
+// 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
+}
-- Parameters can be defined via `schema` or via `content`. Use the `content` form
- for anything other than trivial objects, they can marshal to arbitrary JSON
- structures. When you send them as cookie (`in: cookie`) arguments, we will
- URL encode them, since JSON delimiters aren't allowed in cookies.
+// 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
+ }
-## Using SecurityProviders
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ return err
+}
-If you generate client-code, you can use some default-provided security providers
-which help you to use the various OpenAPI 3 Authentication mechanism.
+// 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
+}
-```go
- import (
- "github.com/deepmap/oapi-codegen/pkg/securityprovider"
- )
+// 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
+}
- func CreateSampleProviders() error {
- // Example BasicAuth
- // See: https://swagger.io/docs/specification/authentication/basic-authentication/
- basicAuthProvider, basicAuthProviderErr := securityprovider.NewSecurityProviderBasicAuth("MY_USER", "MY_PASS")
- if basicAuthProviderErr != nil {
- panic(basicAuthProviderErr)
- }
+// 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
+ }
- // Example BearerToken
- // See: https://swagger.io/docs/specification/authentication/bearer-authentication/
- bearerTokenProvider, bearerTokenProviderErr := securityprovider.NewSecurityProviderBearerToken("MY_TOKEN")
- if bearerTokenProviderErr != nil {
- panic(bearerTokenProviderErr)
- }
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ return err
+}
- // Example ApiKey provider
- // See: https://swagger.io/docs/specification/authentication/api-keys/
- apiKeyProvider, apiKeyProviderErr := securityprovider.NewSecurityProviderApiKey("query", "myApiKeyParam", "MY_API_KEY")
- if apiKeyProviderErr != nil {
- panic(apiKeyProviderErr)
- }
+func (t ClientAndMaybeIdentity) MarshalJSON() ([]byte, error) {
+ b, err := t.union.MarshalJSON()
+ return b, err
+}
- // Example providing your own provider using an anonymous function wrapping in the
- // InterceptoFn adapter. The behaviour between the InterceptorFn and the Interceptor interface
- // are the same as http.HandlerFunc and http.Handler.
- customProvider := func(req *http.Request, ctx context.Context) error {
- // Just log the request header, nothing else.
- log.Println(req.Header)
- return nil
- }
+func (t *ClientAndMaybeIdentity) UnmarshalJSON(b []byte) error {
+ err := t.union.UnmarshalJSON(b)
+ return err
+}
- // Exhaustive list of some defaults you can use to initialize a Client.
- // If you need to override the underlying httpClient, you can use the option
- //
- // WithHTTPClient(httpClient *http.Client)
- //
- client, clientErr := NewClient("https://api.deepmap.com", WithRequestEditorFn(apiKeyProvider.Intercept))
- return nil
- }
```
-## Extensions
+
-- `x-go-type`: specifies Go type name. It allows you to specify the type name for a schema, and
- will override any default value. This extended property isn't supported in all parts of
- OpenAPI, so please refer to the spec as to where it's allowed. Swagger validation tools will
- flag incorrect usage of this property.
-- `x-go-type-skip-optional-pointer`: specifies if the Go type should or should not be a pointer
- when the property is optional. If set to true, the type will not be a pointer if the field is
- optional or nullable. If set to false, the type will be a pointer.
-
- ```yaml
- properties:
- field:
- type: string
- x-go-type-skip-optional-pointer: true
- ```
-
- In the example above, the `field` field will be of type `string` instead of `*string`. This is
- useful when you want to handle the case of an empty string differently than a null value.
-
-- `x-go-name`: specifies Go field name. It allows you to specify the field name for a schema, and
- will override any default value. This extended property isn't supported in all parts of
- OpenAPI, so please refer to the spec as to where it's allowed. Swagger validation tools will
- flag incorrect usage of this property.
-- `x-go-type-name`: This property allows for assigning a Go type name to some part of a schema,
- such as generating a type name for an anonymous object inside another object, or renaming
- an enum. It differs from `x-go-type`, in that it doesn't completely replace some type reference,
- but simply names it.
-- `x-go-json-ignore`: sets tag to `-` to ignore the field in json completely.
-- `x-oapi-codegen-extra-tags`: adds extra Go field tags to the generated struct field. This is
- useful for interfacing with tag based ORM or validation libraries. The extra tags that
- are added are in addition to the regular json tags that are generated. If you specify your
- own `json` tag, you will override the default one.
-
- ```yaml
- components:
- schemas:
- Object:
- properties:
- name:
- type: string
- x-oapi-codegen-extra-tags:
- tag1: value1
- tag2: value2
- ```
+
- In the example above, field `name` will be declared as:
+```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
+}
- ```
- Name string `json:"name" tag1:"value1" tag2:"value2"`
- ```
+// 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
+}
-- `x-go-type-import`: adds extra Go imports to your generated code. It can help you, when you want to
- choose your own import package for `x-go-type`.
+// 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
+ }
- ```yaml
- schemas:
- Pet:
- properties:
- age:
- x-go-type: myuuid.UUID
- x-go-type-import:
- name: myuuid
- path: github.com/google/uuid
- ```
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ return err
+}
- After code generation you will get this:
+// 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
+}
- ```go
- import (
- ...
- myuuid "github.com/google/uuid"
- )
+// 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
+}
- //Pet defines model for Pet.
- type Pet struct {
- Age *myuuid.UUID `json:"age,omitempty"`
- }
+// 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
+}
- `name` is an optional parameter. Example:
+func (t ClientOrIdentity) MarshalJSON() ([]byte, error) {
+ b, err := t.union.MarshalJSON()
+ return b, err
+}
- ```yaml
- components:
- schemas:
- Pet:
- properties:
- age:
- x-go-type: uuid.UUID
- x-go-type-import:
- path: github.com/google/uuid
- required:
- - age
- ```
+func (t *ClientOrIdentity) UnmarshalJSON(b []byte) error {
+ err := t.union.UnmarshalJSON(b)
+ return err
+}
+```
- After code generation you will get this result:
+
- ```go
- import (
- "github.com/google/uuid"
- )
+For more info, check out [the example code](examples/anyof-allof-oneof/).
- // Pet defines model for Pet.
- type Pet struct {
- Age uuid.UUID `json:"age"`
- }
- ```
+### How can I ignore parts of the spec I don't care about?
-- `x-enum-varnames`: supplies other enum names for the corresponding values. (alias: `x-enumNames`)
+By default, `oapi-codegen` will generate everything from the specification.
- ```yaml
- components:
- schemas:
- Object:
- properties:
- category:
- type: integer
- enum: [0, 1, 2]
- x-enum-varnames:
- - notice
- - warning
- - urgent
- ```
-
- After code generation you will get this result:
-
- ```go
- // Defines values for ObjectCategory.
- const (
- Notice ObjectCategory = 0
- Urgent ObjectCategory = 2
- Warning ObjectCategory = 1
- )
-
- // ObjectCategory defines model for Object.Category.
- type ObjectCategory int
- ```
-
-## Using `oapi-codegen`
-
-The default options for `oapi-codegen` will generate everything; client, server,
-type definitions and embedded swagger spec, but you can generate subsets of
-those via the `-generate` flag. It defaults to `types,client,server,spec`, but
-you can specify any combination of those.
-
-- `types`: generate all type definitions for all types in the OpenAPI spec. This
- will be everything under `#components`, as well as request parameter, request
- body, and response type objects.
-- `server`: generate the Echo server boilerplate. `server` requires the types in the
- same package to compile.
-- `chi-server`: generate the Chi server boilerplate. This code is dependent on
- that produced by the `types` target.
-- `fiber`: generate the Fiber server boilerplate. This code is dependent
- on that produced by the `types` target.
-- `iris`: generate the Iris server boilerplate. This code is dependent
- on that produced by the `types` target.
-- `client`: generate the client boilerplate. It, too, requires the types to be
- present in its package.
-- `spec`: embed the OpenAPI spec into the generated code as a gzipped blob.
- This is then usable with the `OapiRequestValidator`, or to be used by other
- methods that need access to the parsed OpenAPI specification
-- `skip-fmt`: skip running `goimports` on the generated code. This is useful for debugging
- the generated file in case the spec contains weird strings.
-- `skip-prune`: skip pruning unused components from the spec prior to generating
- the code.
-- `import-mapping`: specifies a map of references external OpenAPI specs to go
- Go include paths. Please see below.
-
-So, for example, if you would like to produce only the server code, you could
-run `oapi-codegen -generate types,server`. You could generate `types` and
-`server` into separate files, but both are required for the server code.
-
-`oapi-codegen` can filter paths base on their tags in the openapi definition.
-Use either `-include-tags` or `-exclude-tags` followed by a comma-separated list
-of tags. For instance, to generate a server that serves all paths except those
-tagged with `auth` or `admin`, use the argument, `-exclude-tags="auth,admin"`.
-To generate a server that only handles `admin` paths, use the argument
-`-include-tags="admin"`. When neither of these arguments is present, all paths
-are generated.
-
-`oapi-codegen` can filter schemas based on the option `--exclude-schemas`, which is
-a comma separated list of schema names. For instance, `--exclude-schemas=Pet,NewPet`
-will exclude from generation schemas `Pet` and `NewPet`. This allow to have a
-in the same package a manually defined structure or interface and refer to it
-in the openapi spec.
-
-Since `go generate` commands must be a single line, all the options above can make
-them pretty unwieldy, so you can specify all of the options in a configuration
-file via the `--config` option. Please see the test under
-[`/internal/test/externalref/`](https://github.com/deepmap/oapi-codegen/blob/master/internal/test/externalref/externalref.cfg.yaml)
-for an example. The structure of the file is as follows:
-
-```yaml
-package: externalref
-generate:
- models: true
- embedded-spec: true
-import-mapping:
- ./packageA/spec.yaml: github.com/deepmap/oapi-codegen/internal/test/externalref/packageA
- ./packageB/spec.yaml: github.com/deepmap/oapi-codegen/internal/test/externalref/packageB
-output: externalref.gen.go
+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/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json
output-options:
- skip-prune: true
+ include-tags: []
+ exclude-tags: []
+ include-operation-ids: []
+ exclude-operation-ids: []
+ exclude-schemas: []
```
-Have a look at [`cmd/oapi-codegen/oapi-codegen.go`](https://github.com/deepmap/oapi-codegen/blob/master/cmd/oapi-codegen/oapi-codegen.go#L48)
-to see all the fields on the configuration structure.
+Check [the docs](https://pkg.go.dev/github.com/oapi-codegen/oapi-codegen/v2/pkg/codegen#OutputOptions) for more details of usage.
-### Import Mappings
+### Should I commit the generated code?
-OpenAPI specifications may contain references to other OpenAPI specifications,
-and we need some additional information in order to be able to generate correct
-Go code.
+We recommend doing so, yes, for the following reasons:
-An external reference looks like this:
+- 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
- $ref: ./some_spec.yaml#/components/schemas/Type
+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.
-We assume that you have already generated the boilerplate code for `./some_spec.yaml`
-using `oapi-codegen`, and you have a package which contains the generated code,
-let's call it `github.com/deepmap/some-package`. You need to tell `oapi-codegen` that
-`some_spec.yaml` corresponds to this package, and you would do it by specifying
-this command line argument:
+### Should I lint the generated code?
- -import-mapping=./some_spec.yaml:github.com/deepmap/some-package
+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.
-This tells us that in order to resolve references generated from `some_spec.yaml` we
-need to import `github.com/deepmap/some-package`. You may specify multiple mappings
-by comma separating them in the form `key1:value1,key2:value2`.
+> [!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.
-## What's missing or incomplete
+### I've just updated my version of `kin-openapi`, and now I can't build my code 😠
-This code is still young, and not complete, since we're filling it in as we
-need it. We've not yet implemented several things:
+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.
-- `patternProperties` isn't yet supported and will exit with an error. Pattern
- properties were defined in JSONSchema, and the `kin-openapi` Swagger object
- knows how to parse them, but they're not part of OpenAPI 3.0, so we've left
- them out, as support is very complicated.
+This may lead to breakage in your consuming code, and if so, sorry that's happened!
-## Making changes to code generation
+We'll be aware of the issue, and will work to update both the core `oapi-codegen` and the middlewares accordingly.
-The code generator uses a tool to inline all the template definitions into
-code, so that we don't have to deal with the location of the template files.
-When you update any of the files under the `templates/` directory, you will
-need to regenerate the template inlines:
+## Contributors
- go generate ./pkg/codegen/templates
+We're very appreciative of [the many contributors over the years](https://github.com/oapi-codegen/oapi-codegen/graphs/contributors) and the ongoing use of the project 💜
-All this command does is inline the files ending in `.tmpl` into the specified
-Go file.
+
+ oneOf
- In the example above, field `name` will be declared as:
+```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
+}
- ```
- Name string `json:"name" tag1:"value1" tag2:"value2"`
- ```
+// 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
+}
-- `x-go-type-import`: adds extra Go imports to your generated code. It can help you, when you want to
- choose your own import package for `x-go-type`.
+// 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
+ }
- ```yaml
- schemas:
- Pet:
- properties:
- age:
- x-go-type: myuuid.UUID
- x-go-type-import:
- name: myuuid
- path: github.com/google/uuid
- ```
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ return err
+}
- After code generation you will get this:
+// 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
+}
- ```go
- import (
- ...
- myuuid "github.com/google/uuid"
- )
+// 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
+}
- //Pet defines model for Pet.
- type Pet struct {
- Age *myuuid.UUID `json:"age,omitempty"`
- }
+// 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
+}
- `name` is an optional parameter. Example:
+func (t ClientOrIdentity) MarshalJSON() ([]byte, error) {
+ b, err := t.union.MarshalJSON()
+ return b, err
+}
- ```yaml
- components:
- schemas:
- Pet:
- properties:
- age:
- x-go-type: uuid.UUID
- x-go-type-import:
- path: github.com/google/uuid
- required:
- - age
- ```
+func (t *ClientOrIdentity) UnmarshalJSON(b []byte) error {
+ err := t.union.UnmarshalJSON(b)
+ return err
+}
+```
- After code generation you will get this result:
+
+
+ 
+
+
+ 
+
+