-// Pet defines model for Pet.
-type Pet struct {
- // Unique id of the pet
- Id int64 `json:"id"`
+
-If you changed the OpenAPI specification to make the parameter required, the
-`FindPetsParams` structure will contain the type by value:
-```go
-type FindPetsParams struct {
- Tags *[]string `json:"tags,omitempty"`
- Limit int32 `json:"limit"`
-}
-```
-### Registering handlers
-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`
+### `additionalProperties` as `integer`s
-Boilerplate
- // Name of the pet - Name string `json:"name"` +```go - // Type of the pet - Tag *string `json:"tag,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 } -// Type definition for component schema "Pets" -type Pets []Pet -``` +// 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 +} -It's best to define objects under `/components` field in the schema, since -those will be turned into named Go types. If you use inline types in your -handler definitions, we will generate inline, anonymous Go types, but those -are more tedious to deal with since you will have to redeclare them at every -point of use. +// 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 + } -For each element in the `paths` map in OpenAPI, we will generate a Go handler -function in an interface object. Here is the generated Go interface for our -Echo 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 ServerInterface interface { - // (GET /pets) - FindPets(ctx echo.Context, params FindPetsParams) error - // (POST /pets) - AddPet(ctx echo.Context) error - // (DELETE /pets/{id}) - DeletePet(ctx echo.Context, id int64) error - // (GET /pets/{id}) - FindPetById(ctx echo.Context, id int64) error + 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 } -``` -These are the functions which you will implement yourself in order to create -a server conforming to the API specification. Normally, all the arguments and -parameters are stored on the `echo.Context` in handlers, so we do the tedious -work of unmarshalling the JSON automatically, simply passing values into -your handlers. +// Override default JSON handling for Thing to handle AdditionalProperties +func (a Thing) MarshalJSON() ([]byte, error) { + var err error + object := make(map[string]json.RawMessage) -Notice that `FindPetById` takes a parameter `id int64`. All path arguments -will be passed as arguments to your function, since they are mandatory. + object["id"], err = json.Marshal(a.Id) + if err != nil { + return nil, fmt.Errorf("error marshaling 'id': %w", err) + } -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: - ```go -// Parameters object for FindPets -type FindPetsParams struct { - Tags *[]string `json:"tags,omitempty"` - Limit *int32 `json:"limit,omitempty"` + 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) } ``` -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. +Echo
+```yaml
+components:
+ schemas:
+ Thing:
+ type: object
+ required:
+ - id
+ properties:
+ id:
+ type: integer
+ # simple type
+ additionalProperties:
+ type: integer
+```
-Code generated using `-generate server`.
+Will generate:
-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:
```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.
+
+
+
+// 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
-You would register the generated handlers as follows: ```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)
+
+ object["id"], err = json.Marshal(a.Id)
+ if err != nil {
+ return nil, fmt.Errorf("error marshaling 'id': %w", err)
+ }
- r := chi.NewRouter()
- r.Mount("/", 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)
}
```
-Gin
+
+
+
-Boilerplate
+ ```go -import ( - "github.com/gin-gonic/gin" - "github.com/deepmap/oapi-codegen/examples/petstore-expanded/gin/api" - middleware "github.com/deepmap/oapi-codegen/pkg/gin-middleware" -) +// 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") + } -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) + } - r := gin.Default() - r.Use(middleware.OapiRequestValidator(swagger)) - r = api.RegisterHandlers(r, petStore) + 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) } ``` -net/http
+
-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.
+
-#### Additional Properties in type definitions
+Example, using default configuration
-Short example: -```go -type PetStoreImpl struct {} -func (*PetStoreImpl) GetPets(ctx context.Context, request GetPetsRequestObject) (GetPetsResponseObject, error) { - var result []Pet - // Implement me - return GetPets200JSONResponse(result), nil -} +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 ``` -For a complete example see `/examples/petstore-expanded/strict`. -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: +This will produce: + ```go -func SetupHandler() { - var myApi PetStoreImpl - myStrictApiHandler := api.NewStrictHandler(myApi, nil) - e := echo.New() - petstore.RegisterHandlers(e, &myStrictApiHandler) +// 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) } ``` -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. +
-[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
-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`.
+By default, `oapi-codegen` will perform camel-case conversion, so for a spec such as:
-Say we declared `NewPet` above like so:
```yaml
- NewPet:
+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
- tag:
+ description: The name of the pet.
+ Error:
+ required:
+ - code
+ - message
+ properties:
+ code:
+ type: integer
+ format: int32
+ description: Error code
+ message:
type: string
- additionalProperties:
- 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) {...}
-// Override default JSON handling for NewPet to handle additionalProperties
-func (a *NewPet) UnmarshalJSON(b []byte) error {...}
+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) MarshalJSON() ([]byte, error) {...}w
-```
+## Examples
-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` schemas and tests. Please
-look through those tests for more usage 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`.
-#### oneOf/anyOf/allOf support
+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)
+- [Streamlining Go + Chi Development: Generating Code from an OpenAPI Spec](https://i4o.dev/blog/oapi-codegen-with-chi-router)
+
+Got one to add? Please raise a PR!
+
+## Frequently Asked Questions (FAQs)
+
+### Does `oapi-codegen` support OpenAPI 3.1?
+
+No, we don't currently.
+
+OpenAPI 3.1 support is [awaiting upstream support](https://github.com/oapi-codegen/oapi-codegen/issues/373).
+
+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.
+
+### 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:
-- `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.
```yaml
-schema:
- oneOf:
- - $ref: '#/components/schemas/Cat'
- - $ref: '#/components/schemas/Dog'
+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'
```
-- `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.
-## Generated Client Boilerplate
+This results in the following types:
-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.
+Example, using ToCamelCaseWithInitialisms
-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`.
+By default, `oapi-codegen` will perform camel-case conversion, so for a spec such as:
-Say we declared `NewPet` above like so:
```yaml
- NewPet:
+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
- tag:
+ description: The name of the pet.
+ Error:
+ required:
+ - code
+ - message
+ properties:
+ code:
+ type: integer
+ format: int32
+ description: Error code
+ message:
type: string
- additionalProperties:
- 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) {...}
+
-The interface for the pet store looks like this:
+
- // AddPet request with JSON body
- AddPet(ctx context.Context, body NewPet, reqEditors ...RequestEditorFn) (*http.Response, error)
+Base types
```go -// The interface specification for the client above. -type ClientInterface interface { +// Client defines model for Client. +type Client struct { + Name string `json:"name"` +} + +// Identity defines model for Identity. +type Identity struct { + Issuer string `json:"issuer"` +} +``` - // FindPets request - FindPets(ctx context.Context, params *FindPetsParams, reqEditors ...RequestEditorFn) (*http.Response, error) +
- // DeletePet request
- DeletePet(ctx context.Context, id int64, reqEditors ...RequestEditorFn) (*http.Response, error)
+
- // FindPetById request
- FindPetById(ctx context.Context, id int64, reqEditors ...RequestEditorFn) (*http.Response, error)
+```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"`
}
```
-A Client object which implements the above interface is also generated:
+
+
+allOf
- // FindPetById request
- FindPetById(ctx context.Context, id int64, reqEditors ...RequestEditorFn) (*http.Response, error)
+```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"`
}
```
-A Client object which implements the above interface is also generated:
+
+
+
```go
-// Client which conforms to the OpenAPI3 specification for this service.
-type Client struct {
- // The endpoint of the server conforming to this interface, with scheme,
- // https://api.deepmap.com for example.
- Server string
+import (
+ "encoding/json"
- // HTTP client with any customized settings, such as certificate chains.
- Client http.Client
+ "github.com/oapi-codegen/runtime"
+)
- // A callback for modifying requests which are generated before sending over
- // the network.
- RequestEditors []func(ctx context.Context, req *http.Request) error
+// ClientAndMaybeIdentity defines model for ClientAndMaybeIdentity.
+type ClientAndMaybeIdentity struct {
+ union json.RawMessage
}
-```
-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.
-
-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:
+// 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
+}
- AddPet(ctx context.Context, contentType string, body io.Reader)
+// 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
+}
-2) If you have only a JSON request body, you will get:
+// 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
+ }
- AddPet(ctx context.Context, body NewPet)
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ return err
+}
-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.
+// 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
+}
- AddPet(ctx context.Context, body NewPet)
- AddPetWithBody(ctx context.Context, contentType string, body io.Reader)
+// 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
+}
-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:
+// 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
+ }
-```go
-// Request generator for FindPets
-func NewFindPetsRequest(server string, params *FindPetsParams) (*http.Request, error) {...}
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ return err
+}
-// Request generator for AddPet with JSON body
-func NewAddPetRequest(server string, body NewPet) (*http.Request, error) {...}
+func (t ClientAndMaybeIdentity) MarshalJSON() ([]byte, error) {
+ b, err := t.union.MarshalJSON()
+ return b, err
+}
-// Request generator for AddPet with non-JSON body
-func NewAddPetRequestWithBody(server string, contentType string, body io.Reader) (*http.Request, error) {...}
+func (t *ClientAndMaybeIdentity) UnmarshalJSON(b []byte) error {
+ err := t.union.UnmarshalJSON(b)
+ return err
+}
-// Request generator for DeletePet
-func NewDeletePetRequest(server string, id int64) (*http.Request, error) {...}
-// Request generator for FindPetById
-func NewFindPetByIdRequest(server string, id int64) (*http.Request, error) {...}
```
-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.
+
-There are some caveats to using this code.
-- 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.
+anyOf
```go
-// Client which conforms to the OpenAPI3 specification for this service.
-type Client struct {
- // The endpoint of the server conforming to this interface, with scheme,
- // https://api.deepmap.com for example.
- Server string
+import (
+ "encoding/json"
- // HTTP client with any customized settings, such as certificate chains.
- Client http.Client
+ "github.com/oapi-codegen/runtime"
+)
- // A callback for modifying requests which are generated before sending over
- // the network.
- RequestEditors []func(ctx context.Context, req *http.Request) error
+// ClientAndMaybeIdentity defines model for ClientAndMaybeIdentity.
+type ClientAndMaybeIdentity struct {
+ union json.RawMessage
}
-```
-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.
-
-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:
+// 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
+}
- AddPet(ctx context.Context, contentType string, body io.Reader)
+// 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
+}
-2) If you have only a JSON request body, you will get:
+// 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
+ }
- AddPet(ctx context.Context, body NewPet)
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ return err
+}
-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.
+// 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
+}
- AddPet(ctx context.Context, body NewPet)
- AddPetWithBody(ctx context.Context, contentType string, body io.Reader)
+// 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
+}
-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:
+// 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
+ }
-```go
-// Request generator for FindPets
-func NewFindPetsRequest(server string, params *FindPetsParams) (*http.Request, error) {...}
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ return err
+}
-// Request generator for AddPet with JSON body
-func NewAddPetRequest(server string, body NewPet) (*http.Request, error) {...}
+func (t ClientAndMaybeIdentity) MarshalJSON() ([]byte, error) {
+ b, err := t.union.MarshalJSON()
+ return b, err
+}
-// Request generator for AddPet with non-JSON body
-func NewAddPetRequestWithBody(server string, contentType string, body io.Reader) (*http.Request, error) {...}
+func (t *ClientAndMaybeIdentity) UnmarshalJSON(b []byte) error {
+ err := t.union.UnmarshalJSON(b)
+ return err
+}
-// Request generator for DeletePet
-func NewDeletePetRequest(server string, id int64) (*http.Request, error) {...}
-// Request generator for FindPetById
-func NewFindPetByIdRequest(server string, id int64) (*http.Request, error) {...}
```
-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.
+
-- 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.
+
-## Using SecurityProviders
+```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
+}
-If you generate client-code, you can use some default-provided security providers
-which help you to use the various OpenAPI 3 Authentication mechanism.
+// 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
+ }
-```go
- import (
- "github.com/deepmap/oapi-codegen/pkg/securityprovider"
- )
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ 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)
- }
+// 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
+}
- // Example BearerToken
- // See: https://swagger.io/docs/specification/authentication/bearer-authentication/
- bearerTokenProvider, bearerTokenProviderErr := securityprovider.NewSecurityProviderBearerToken("MY_TOKEN")
- if bearerTokenProviderErr != nil {
- panic(bearerTokenProviderErr)
- }
+// 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
+}
- // 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)
- }
+// 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
+ }
- // 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
- }
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ 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:
-
-- `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-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-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:
-
- ```
- Name string `json:"name" tag1:"value1" tag2:"value2"`
- ```
-- `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`.
-
- ```yaml
- schemas:
- Pet:
- properties:
- age:
- x-go-type: myuuid.UUID
- x-go-type-import:
- name: myuuid
- path: github.com/google/uuid
- ```
- After code generation you will get this:
- ```go
- import (
- ...
- myuuid "github.com/google/uuid"
- )
-
- //Pet defines model for Pet.
- type Pet struct {
- Age *myuuid.UUID `json:"age,omitempty"`
- }
-
- ```
- `name` is an optional parameter. Example:
-
- ```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) MarshalJSON() ([]byte, error) {
+ b, err := t.union.MarshalJSON()
+ return b, err
+}
- After code generation you will get this result:
+func (t *ClientOrIdentity) UnmarshalJSON(b []byte) error {
+ err := t.union.UnmarshalJSON(b)
+ return err
+}
+```
- ```go
- import (
- "github.com/google/uuid"
- )
+
- // Pet defines model for Pet.
- type Pet struct {
- Age uuid.UUID `json:"age"`
- }
- ```
+For more info, check out [the example code](examples/anyof-allof-oneof/).
-- `x-enum-varnames`: supplies other enum names for the corresponding values. (alias: `x-enumNames`)
+### How can I ignore parts of the spec I don't care about?
- ```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.
-- `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
+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/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.
+
+### 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.
-### Import Mappings
+### Should I lint 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 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.
-An external reference looks like this:
+> [!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.
- $ref: ./some_spec.yaml#/components/schemas/Type
+### I've just updated my version of `kin-openapi`, and now I can't build my code 😠
-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:
+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.
- -import-mapping=./some_spec.yaml:github.com/deepmap/some-package
+This may lead to breakage in your consuming code, and if so, sorry that's happened!
-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`.
+We'll be aware of the issue, and will work to update both the core `oapi-codegen` and the middlewares accordingly.
-## What's missing or incomplete
+## Contributors
-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:
+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 💜
-- `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.
+
+ oneOf
-## Using SecurityProviders
+```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
+}
-If you generate client-code, you can use some default-provided security providers
-which help you to use the various OpenAPI 3 Authentication mechanism.
+// 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
+ }
-```go
- import (
- "github.com/deepmap/oapi-codegen/pkg/securityprovider"
- )
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ 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)
- }
+// 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
+}
- // Example BearerToken
- // See: https://swagger.io/docs/specification/authentication/bearer-authentication/
- bearerTokenProvider, bearerTokenProviderErr := securityprovider.NewSecurityProviderBearerToken("MY_TOKEN")
- if bearerTokenProviderErr != nil {
- panic(bearerTokenProviderErr)
- }
+// 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
+}
- // 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)
- }
+// 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
+ }
- // 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
- }
+ merged, err := runtime.JSONMerge(t.union, b)
+ t.union = merged
+ 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:
-
-- `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-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-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:
-
- ```
- Name string `json:"name" tag1:"value1" tag2:"value2"`
- ```
-- `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`.
-
- ```yaml
- schemas:
- Pet:
- properties:
- age:
- x-go-type: myuuid.UUID
- x-go-type-import:
- name: myuuid
- path: github.com/google/uuid
- ```
- After code generation you will get this:
- ```go
- import (
- ...
- myuuid "github.com/google/uuid"
- )
-
- //Pet defines model for Pet.
- type Pet struct {
- Age *myuuid.UUID `json:"age,omitempty"`
- }
-
- ```
- `name` is an optional parameter. Example:
-
- ```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) MarshalJSON() ([]byte, error) {
+ b, err := t.union.MarshalJSON()
+ return b, err
+}
- After code generation you will get this result:
+func (t *ClientOrIdentity) UnmarshalJSON(b []byte) error {
+ err := t.union.UnmarshalJSON(b)
+ return err
+}
+```
- ```go
- import (
- "github.com/google/uuid"
- )
+
+
+ 
+
+
+ 
+
+