`oapi-codegen`

oapi-codegen is a command-line tool and library to convert OpenAPI specifications to Go code, be it server-side implementations, API clients, or simply HTTP models.

Using oapi-codegen allows you to reduce the boilerplate required to create or integrate with services based on OpenAPI 3.0, and instead focus on writing your business logic, and working on the real value-add for your organisation.

With oapi-codegen, there are a few Key Design Decisions we've made, including:

idiomatic Go, where possible
fairly simple generated code, erring on the side of duplicate code over nicely refactored code
supporting as much of OpenAPI 3.x as is possible, alongside Go's type system

oapi-codegen is one part of a wider ecosystem, which can be found described in further detail in the oapi-codegen organisation on GitHub.

⚠️ This README may be for the latest development version, which may contain unreleased changes. Please ensure you're looking at the README for the latest release version.

Install

It is recommended to follow the tools.go pattern for managing the dependency of oapi-codegen alongside your core application.

This would give you a tools/tools.go:

//go:build tools// +build toolspackage main
import (
_ "github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen"
)

Then, each invocation of oapi-codegen would be used like so:

//go:generate go run github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen --config=config.yaml ../../api.yaml

Alternatively, you can install it as a binary with:

$ go install github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen@latest
$ oapi-codegen -version

Which then means you can invoke it like so:

//go:generate oapi-codegen --config=config.yaml ../../api.yaml

Pinning to commits

While the project does not (yet) have a defined release cadence, there may be cases where you want to pull in yet-unreleased changes to your codebase.

Therefore, you may want to pin your dependency on oapi-codegen to a given commit hash, rather than a tag.

This is officially recommended for consumers of oapi-codegen, who want features/bug fixes that haven't yet been released.

We aim to keep the default branch ready-to-release so you should be able to safely pin.

To do so, you can run:

# pin to the latest version on the default branch
$ go get github.com/deepmap/oapi-codegen/v2@master
# alternatively, to a commit hash i.e. https://github.com/deepmap/oapi-codegen/commit/71e916c59688a6379b5774dfe5904ec222b9a537
$ go get github.com/deepmap/oapi-codegen/v2@71e916c59688a6379b5774dfe5904ec222b9a537

This will then make a change such as:

diff --git go.mod go.mod
index 44f29a4..436a780 100644
--- go.mod+++ go.mod@@ -2,21 +2,20 @@-require github.com/deepmap/oapi-codegen/v2 v2.1.0+require github.com/deepmap/oapi-codegen/v2 v2.1.1-0.20240331212514-80f0b978ef16

Usage

oapi-codegen is largely configured using a YAML configuration file, to simplify the number of flags that users need to remember, and to make reading the go:generate command less daunting.

For full details of what is supported, it's worth checking out the GoDoc for codegen.Configuration.

We also have a JSON Schema that can be used by IDEs/editors with the Language Server Protocol (LSP) to perform intelligent suggestions, i.e.:

# yaml-language-server: $schema=https://raw.githubusercontent.com/deepmap/oapi-codegen/HEAD/configuration-schema.jsonpackage: api# ...

Backwards compatibility

Although we strive to retain backwards compatibility - as a project that's using a stable API per SemVer - there are sometimes opportunities we must take to fix a bug that could cause a breaking change for people relying upon the behaviour.

In this case, we will expose a compatibility option to restore old behaviour.

Features

At a high level, oapi-codegen supports:

Generating server-side boilerplate for a number of servers (docs)
Generating client API boilerplate (docs)
Generating the types (docs)
Splitting large OpenAPI specs across multiple packages(docs)
- This is also known as "Import Mapping" or "external references" across our documentation / discussion in GitHub issues

What does it look like?

Below we can see a trimmed down example taken from the OpenAPI Petstore example:

// generated codetypeServerInterfaceinterface {
// ...// Returns all pets// (GET /pets)FindPets(w http.ResponseWriter, r*http.Request, paramsFindPetsParams)
// ...
}
// FindPets operation middlewarefunc (siw*ServerInterfaceWrapper) FindPets(w http.ResponseWriter, r*http.Request) {
ctx:=r.Context()
varerrerror// Parameter object where we will unmarshal all parameters from the contextvarparamsFindPetsParams// ------------- Optional query parameter "tags" -------------err=runtime.BindQueryParameter("form", true, false, "tags", r.URL.Query(), &params.Tags)
iferr!=nil {
siw.ErrorHandlerFunc(w, r, &InvalidParamFormatError{ParamName: "tags", Err: err})
return
}
// ------------- Optional query parameter "limit" -------------err=runtime.BindQueryParameter("form", true, false, "limit", r.URL.Query(), &params.Limit)
iferr!=nil {
siw.ErrorHandlerFunc(w, r, &InvalidParamFormatError{ParamName: "limit", Err: err})
return
}
handler:=http.Handler(http.HandlerFunc(func(w http.ResponseWriter, r*http.Request) {
siw.Handler.FindPets(w, r, params)
}))
for_, middleware:=rangesiw.HandlerMiddlewares {
handler=middleware(handler)
}
handler.ServeHTTP(w, r.WithContext(ctx))
}
// HandlerWithOptions creates http.Handler with additional optionsfuncHandlerWithOptions(siServerInterface, optionsStdHTTPServerOptions) http.Handler {
m:=options.BaseRouterifm==nil {
m=http.NewServeMux()
}
ifoptions.ErrorHandlerFunc==nil {
options.ErrorHandlerFunc=func(w http.ResponseWriter, r*http.Request, errerror) {
http.Error(w, err.Error(), http.StatusBadRequest)
}
}
wrapper:=ServerInterfaceWrapper{
Handler: si,
HandlerMiddlewares: options.Middlewares,
ErrorHandlerFunc: options.ErrorHandlerFunc,
}
m.HandleFunc("GET "+options.BaseURL+"/pets", wrapper.FindPets)
returnm
}

Then, in your own code, you implement the underlying logic for the FindPets implementation:

typePetStorestruct {
Petsmap[int64]PetNextIdint64Lock sync.Mutex
}
// Make sure we conform to ServerInterfacevar_ServerInterface= (*PetStore)(nil)
funcNewPetStore() *PetStore {
return&PetStore{
Pets: make(map[int64]Pet),
NextId: 1000,
}
}
// FindPets implements all the handlers in the ServerInterfacefunc (p*PetStore) FindPets(w http.ResponseWriter, r*http.Request, paramsFindPetsParams) {
p.Lock.Lock()
deferp.Lock.Unlock()
varresult []Petfor_, pet:=rangep.Pets {
ifparams.Tags!=nil {
// If we have tags, filter pets by tagfor_, t:=range*params.Tags {
ifpet.Tag!=nil&& (*pet.Tag==t) {
result=append(result, pet)
}
}
} else {
// Add all pets if we're not filteringresult=append(result, pet)
}
ifparams.Limit!=nil {
l:=int(*params.Limit)
iflen(result) >=l {
// We're at the limitbreak
}
}
}
w.WriteHeader(http.StatusOK)
_=json.NewEncoder(w).Encode(result)
}

As we can see, oapi-codegen simplifies some of the boilerplate by taking parameters out of the request and instead allows us to focus on the implementation.

You'll note that there's still a bit more marshaling of request/response data, which is further reduced by using the Strict server functionality.

When using the strict server, you'll have the following generated code:

// StrictServerInterface represents all server handlers.typeStrictServerInterfaceinterface {
// ...// Returns all pets// (GET /pets)FindPets(ctx context.Context, requestFindPetsRequestObject) (FindPetsResponseObject, error)
// ...
}
funcNewStrictHandlerWithOptions(ssiStrictServerInterface, middlewares []StrictMiddlewareFunc, optionsStrictHTTPServerOptions) ServerInterface {
return&strictHandler{ssi: ssi, middlewares: middlewares, options: options}
}
// FindPets operation middlewarefunc (sh*strictHandler) FindPets(w http.ResponseWriter, r*http.Request, paramsFindPetsParams) {
varrequestFindPetsRequestObjectrequest.Params=paramshandler:=func(ctx context.Context, w http.ResponseWriter, r*http.Request, requestinterface{}) (interface{}, error) {
returnsh.ssi.FindPets(ctx, request.(FindPetsRequestObject))
}
for_, middleware:=rangesh.middlewares {
handler=middleware(handler, "FindPets")
}
response, err:=handler(r.Context(), w, r, request)
iferr!=nil {
sh.options.ResponseErrorHandlerFunc(w, r, err)
} elseifvalidResponse, ok:=response.(FindPetsResponseObject); ok {
iferr:=validResponse.VisitFindPetsResponse(w); err!=nil {
sh.options.ResponseErrorHandlerFunc(w, r, err)
}
} elseifresponse!=nil {
sh.options.ResponseErrorHandlerFunc(w, r, fmt.Errorf("unexpected response type: %T", response))
}
}

Then, in your own code, you implement the underlying logic for the FindPets implementation:

// Make sure we conform to StrictServerInterfacevar_StrictServerInterface= (*PetStore)(nil)
funcNewPetStore() *PetStore {
return&PetStore{
Pets: make(map[int64]Pet),
NextId: 1000,
}
}
// FindPets implements all the handlers in the ServerInterfacefunc (p*PetStore) FindPets(ctx context.Context, requestFindPetsRequestObject) (FindPetsResponseObject, error) {
p.Lock.Lock()
deferp.Lock.Unlock()
varresult []Petfor_, pet:=rangep.Pets {
ifrequest.Params.Tags!=nil {
// If we have tags, filter pets by tagfor_, t:=range*request.Params.Tags {
ifpet.Tag!=nil&& (*pet.Tag==t) {
result=append(result, pet)
}
}
} else {
// Add all pets if we're not filteringresult=append(result, pet)
}
ifrequest.Params.Limit!=nil {
l:=int(*request.Params.Limit)
iflen(result) >=l {
// We're at the limitbreak
}
}
}
returnFindPets200JSONResponse(result), nil
}

We can see that this provides the best means to focus on the implementation of the business logic within the endpoint, rather than (un)marshalling types to and from JSON, or wrangling cookies or headers.

Key design decisions

Produce an interface that can be satisfied by your implementation, with reduced boilerplate
Bulk processing and parsing of OpenAPI document in Go
Resulting output is using Go's text/templates, which are user-overridable
Attempts to produce Idiomatic Go
Single-file output
Support multiple OpenAPI files by having a package-per-OpenAPI file
Support of OpenAPI 3.0
- OpenAPI 3.1 support is awaiting upstream support
- Note that this does not include OpenAPI 2.0 (aka Swagger)
Extract parameters from requests, to reduce work required by your implementation
Implicit additionalProperties are ignored by default (more details)
Prune unused types by default

Generating server-side boilerplate

oapi-codegen shines by making it fairly straightforward (note that this is a purposeful choice of wording here - we want to avoid words like "easy") to generate the server-side boilerplate for a backend API.

Below you can find the supported servers, and more information about how to implement a server using them.

To provide you a fully Test Driven Development style test harness to confirm you are following the specification, you could use a tool such as openapi.tanna.dev/go/validator, or craft your own.

Supported Servers

Right now, we support the following servers, and are supportive of adding new servers, too!

Server	`generate` flag to enable code generation	Example usage
Chi	`chi-server`	For a Chi server, you will want a configuration file such as: # yaml-language-server: ...package: apigenerate: chi-server: truemodels: trueoutput: gen.go To implement this, check out the Chi docs.
Echo	`echo-server`	For an Echo server, you will want a configuration file such as: # yaml-language-server: ...package: apigenerate: echo-server: truemodels: trueoutput: gen.go To implement this, check out the Echo docs.
Fiber	`fiber-server`	For a Fiber server, you will want a configuration file such as: # yaml-language-server: ...package: apigenerate: fiber-server: truemodels: trueoutput: gen.go To implement this, check out the Fiber docs.
Gin	`gin-server`	For a Gin server, you will want a configuration file such as: # yaml-language-server: ...package: apigenerate: gin-server: truemodels: trueoutput: gen.go To implement this, check out the Gin docs.
gorilla/mux	`gorilla-server`	For a gorilla/mux server, you will want a configuration file such as: # yaml-language-server: ...package: apigenerate: gorilla-server: truemodels: trueoutput: gen.go To implement this, check out the gorilla/mux docs.
Iris	`iris-server`	For a Iris server, you will want a configuration file such as: # yaml-language-server: ...package: apigenerate: iris-server: truemodels: trueoutput: gen.go To implement this, check out the Iris docs.
1.22+ `net/http`	`std-http-server`	To use purely `net/http` (for Go 1.22+), you will want a configuration file such as: # yaml-language-server: ...package: apigenerate: std-http-server: truemodels: trueoutput: gen.go To implement this, check out the Go 1.22+ `net/http` docs.

Go 1.22+ `net/http`

As of Go 1.22, enhancements have been made to the routing of the net/http package in the standard library, which makes it a great starting point for implementing a server with, before needing to reach for another router or a full framework.

For instance, let's take this straightforward specification:

openapi: "3.0.0"info:
version: 1.0.0title: Minimal ping API serverpaths:
/ping:
get:
responses:
'200':
description: pet responsecontent:
application/json:
schema:
$ref: '#/components/schemas/Pong'components:
schemas:
# base typesPong:
type: objectrequired:
- pingproperties:
ping:
type: stringexample: pong

This then generates code such as:

// Pong defines model for Pong.typePongstruct {
Pingstring`json:"ping"`
}
// ServerInterface represents all server handlers.typeServerInterfaceinterface {
// (GET /ping)GetPing(w http.ResponseWriter, r*http.Request)
}
funcHandlerFromMux(siServerInterface, m*http.ServeMux) http.Handler {
returnHandlerWithOptions(si, StdHTTPServerOptions{
BaseRouter: m,
})
}
// HandlerWithOptions creates http.Handler with additional optionsfuncHandlerWithOptions(siServerInterface, optionsStdHTTPServerOptions) http.Handler {
m:=options.BaseRouter// ... omitted for brevitym.HandleFunc("GET "+options.BaseURL+"/ping", wrapper.GetPing)
returnm
}

To implement this HTTP server, we need to write the following code in our api/impl.go:

import (
"encoding/json""net/http"
)
// optional code omittedtypeServerstruct{}
funcNewServer() Server {
returnServer{}
}
// (GET /ping)func (Server) GetPing(w http.ResponseWriter, r*http.Request) {
resp:=Pong{
Ping: "pong",
}
w.WriteHeader(http.StatusOK)
_=json.NewEncoder(w).Encode(resp)
}

Now we've got our implementation, we can then write the following code to wire it up and get a running server:

import (
"log""net/http""github.com/deepmap/oapi-codegen/v2/examples/minimal-server/stdhttp/api"
)
funcmain() {
// create a type that satisfies the `api.ServerInterface`, which contains an implementation of every operation from the generated codeserver:=api.NewServer()
r:=http.NewServeMux()
// get an `http.Handler` that we can useh:=api.HandlerFromMux(server, r)
s:=&http.Server{
Handler: h,
Addr: "0.0.0.0:8080",
}
// And we serve HTTP until the world ends.log.Fatal(s.ListenAndServe())
}

Note

This doesn't include validation of incoming requests.

Note

If you feel like you've done everything right, but are still receiving 404 page not found errors, make sure that you've got the go directive in your go.mod updated to:

go1.22

Chi

For instance, let's take this straightforward specification:

openapi: "3.0.0"info:
version: 1.0.0title: Minimal ping API serverpaths:
/ping:
get:
responses:
'200':
description: pet responsecontent:
application/json:
schema:
$ref: '#/components/schemas/Pong'components:
schemas:
# base typesPong:
type: objectrequired:
- pingproperties:
ping:
type: stringexample: pong

This then generates code such as:

// Pong defines model for Pong.typePongstruct {
Pingstring`json:"ping"`
}
// ServerInterface represents all server handlers.typeServerInterfaceinterface {
// (GET /ping)GetPing(w http.ResponseWriter, r*http.Request)
}
// HandlerFromMux creates http.Handler with routing matching OpenAPI spec based on the provided mux.funcHandlerFromMux(siServerInterface, r*mux.Router) http.Handler {
returnHandlerWithOptions(si, ChiServerOptions{
BaseRouter: r,
})
}
// HandlerWithOptions creates http.Handler with additional optionsfuncHandlerWithOptions(siServerInterface, optionsChiServerOptions) http.Handler {
r:=options.BaseRouter// ...r.Group(func(r chi.Router) {
r.Get(options.BaseURL+"/ping", wrapper.GetPing)
})
returnr
}

To implement this HTTP server, we need to write the following code in our api/impl.go:

import (
"encoding/json""net/http"
)
// optional code omittedtypeServerstruct{}
funcNewServer() Server {
returnServer{}
}
// (GET /ping)func (Server) GetPing(w http.ResponseWriter, r*http.Request) {
resp:=Pong{
Ping: "pong",
}
w.WriteHeader(http.StatusOK)
_=json.NewEncoder(w).Encode(resp)
}

Now we've got our implementation, we can then write the following code to wire it up and get a running server:

import (
"log""net/http""github.com/deepmap/oapi-codegen/v2/examples/minimal-server/chi/api""github.com/go-chi/chi/v5"
)
funcmain() {
// create a type that satisfies the `api.ServerInterface`, which contains an implementation of every operation from the generated codeserver:=api.NewServer()
r:=chi.NewMux()
// get an `http.Handler` that we can useh:=api.HandlerFromMux(server, r)
s:=&http.Server{
Handler: h,
Addr: "0.0.0.0:8080",
}
// And we serve HTTP until the world ends.log.Fatal(s.ListenAndServe())
}

Note

This doesn't include validation of incoming requests.

gorilla/mux

For instance, let's take this straightforward specification:

openapi: "3.0.0"info:
version: 1.0.0title: Minimal ping API serverpaths:
/ping:
get:
responses:
'200':
description: pet responsecontent:
application/json:
schema:
$ref: '#/components/schemas/Pong'components:
schemas:
# base typesPong:
type: objectrequired:
- pingproperties:
ping:
type: stringexample: pong

This then generates code such as:

// Pong defines model for Pong.typePongstruct {
Pingstring`json:"ping"`
}
// ServerInterface represents all server handlers.typeServerInterfaceinterface {
// (GET /ping)GetPing(w http.ResponseWriter, r*http.Request)
}
// HandlerFromMux creates http.Handler with routing matching OpenAPI spec based on the provided mux.funcHandlerFromMux(siServerInterface, r*mux.Router) http.Handler {
returnHandlerWithOptions(si, GorillaServerOptions{
BaseRouter: r,
})
}
// HandlerWithOptions creates http.Handler with additional optionsfuncHandlerWithOptions(siServerInterface, optionsGorillaServerOptions) http.Handler {
r:=options.BaseRouter// ...r.HandleFunc(options.BaseURL+"/ping", wrapper.GetPing).Methods("GET")
returnr
}

To implement this HTTP server, we need to write the following code in our api/impl.go:

import (
"encoding/json""net/http"
)
// optional code omittedtypeServerstruct{}
funcNewServer() Server {
returnServer{}
}
// (GET /ping)func (Server) GetPing(w http.ResponseWriter, r*http.Request) {
resp:=Pong{
Ping: "pong",
}
w.WriteHeader(http.StatusOK)
_=json.NewEncoder(w).Encode(resp)
}

Now we've got our implementation, we can then write the following code to wire it up and get a running server:

import (
"log""net/http""github.com/deepmap/oapi-codegen/v2/examples/minimal-server/gorillamux/api""github.com/gorilla/mux"
)
funcmain() {
// create a type that satisfies the `api.ServerInterface`, which contains an implementation of every operation from the generated codeserver:=api.NewServer()
r:=mux.NewRouter()
// get an `http.Handler` that we can useh:=api.HandlerFromMux(server, r)
s:=&http.Server{
Handler: h,
Addr: "0.0.0.0:8080",
}
// And we serve HTTP until the world ends.log.Fatal(s.ListenAndServe())
}

Note

This doesn't include validation of incoming requests.

Echo server

For instance, let's take this straightforward specification:

openapi: "3.0.0"info:
version: 1.0.0title: Minimal ping API serverpaths:
/ping:
get:
responses:
'200':
description: pet responsecontent:
application/json:
schema:
$ref: '#/components/schemas/Pong'components:
schemas:
# base typesPong:
type: objectrequired:
- pingproperties:
ping:
type: stringexample: pong

This then generates code such as:

// Pong defines model for Pong.typePongstruct {
Pingstring`json:"ping"`
}
// ServerInterface represents all server handlers.typeServerInterfaceinterface {
// (GET /ping)GetPing(ctx echo.Context) error
}
// This is a simple interface which specifies echo.Route addition functions which// are present on both echo.Echo and echo.Group, since we want to allow using// either of them for path registrationtypeEchoRouterinterface {
// ...GET(pathstring, h echo.HandlerFunc, m...echo.MiddlewareFunc) *echo.Route// ...
}
// RegisterHandlers adds each server route to the EchoRouter.funcRegisterHandlers(routerEchoRouter, siServerInterface) {
RegisterHandlersWithBaseURL(router, si, "")
}
// Registers handlers, and prepends BaseURL to the paths, so that the paths// can be served under a prefix.funcRegisterHandlersWithBaseURL(routerEchoRouter, siServerInterface, baseURLstring) {
// ...router.GET(baseURL+"/ping", wrapper.GetPing)
}

To implement this HTTP server, we need to write the following code in our api/impl.go:

import (
"net/http""github.com/labstack/echo/v4"
)
// optional code omittedtypeServerstruct{}
funcNewServer() Server {
returnServer{}
}
// (GET /ping)func (Server) GetPing(ctx echo.Context) error {
resp:=Pong{
Ping: "pong",
}
returnctx.JSON(http.StatusOK, resp)
}

Now we've got our implementation, we can then write the following code to wire it up and get a running server:

import (
"log""github.com/deepmap/oapi-codegen/v2/examples/minimal-server/echo/api""github.com/labstack/echo/v4"
)
funcmain() {
// create a type that satisfies the `api.ServerInterface`, which contains an implementation of every operation from the generated codeserver:=api.NewServer()
e:=echo.New()
api.RegisterHandlers(e, server)
// And we serve HTTP until the world ends.log.Fatal(e.Start("0.0.0.0:8080"))
}

Note

This doesn't include validation of incoming requests.

Fiber server

For instance, let's take this straightforward specification:

openapi: "3.0.0"info:
version: 1.0.0title: Minimal ping API serverpaths:
/ping:
get:
responses:
'200':
description: pet responsecontent:
application/json:
schema:
$ref: '#/components/schemas/Pong'components:
schemas:
# base typesPong:
type: objectrequired:
- pingproperties:
ping:
type: stringexample: pong

This then generates code such as:

// Pong defines model for Pong.typePongstruct {
Pingstring`json:"ping"`
}
// ServerInterface represents all server handlers.typeServerInterfaceinterface {
// (GET /ping)GetPing(c*fiber.Ctx) error
}
// RegisterHandlers creates http.Handler with routing matching OpenAPI spec.funcRegisterHandlers(router fiber.Router, siServerInterface) {
RegisterHandlersWithOptions(router, si, FiberServerOptions{})
}
// RegisterHandlersWithOptions creates http.Handler with additional optionsfuncRegisterHandlersWithOptions(router fiber.Router, siServerInterface, optionsFiberServerOptions) {
// ...router.Get(options.BaseURL+"/ping", wrapper.GetPing)
}

To implement this HTTP server, we need to write the following code in our api/impl.go:

import (
"net/http""github.com/gofiber/fiber/v2"
)
// ensure that we've conformed to the `ServerInterface` with a compile-time checkvar_ServerInterface= (*Server)(nil)
typeServerstruct{}
funcNewServer() Server {
returnServer{}
}
// (GET /ping)func (Server) GetPing(ctx*fiber.Ctx) error {
resp:=Pong{
Ping: "pong",
}
returnctx.
Status(http.StatusOK).
JSON(resp)
}

Now we've got our implementation, we can then write the following code to wire it up and get a running server:

import (
"log""github.com/deepmap/oapi-codegen/v2/examples/minimal-server/fiber/api""github.com/gofiber/fiber/v2"
)
funcmain() {
// create a type that satisfies the `api.ServerInterface`, which contains an implementation of every operation from the generated codeserver:=api.NewServer()
app:=fiber.New()
api.RegisterHandlers(app, server)
// And we serve HTTP until the world ends.log.Fatal(app.Listen("0.0.0.0:8080"))
}

Note

This doesn't include validation of incoming requests.

Gin server

For instance, let's take this straightforward specification:

openapi: "3.0.0"info:
version: 1.0.0title: Minimal ping API serverpaths:
/ping:
get:
responses:
'200':
description: pet responsecontent:
application/json:
schema:
$ref: '#/components/schemas/Pong'components:
schemas:
# base typesPong:
type: objectrequired:
- pingproperties:
ping:
type: stringexample: pong

This then generates code such as:

// Pong defines model for Pong.typePongstruct {
Pingstring`json:"ping"`
}
// ServerInterface represents all server handlers.typeServerInterfaceinterface {
// (GET /ping)GetPing(c*gin.Context)
}
// RegisterHandlers creates http.Handler with routing matching OpenAPI spec.funcRegisterHandlers(router gin.IRouter, siServerInterface) {
RegisterHandlersWithOptions(router, si, GinServerOptions{})
}
// RegisterHandlersWithOptions creates http.Handler with additional optionsfuncRegisterHandlersWithOptions(router gin.IRouter, siServerInterface, optionsGinServerOptions) {
// ...router.GET(options.BaseURL+"/ping", wrapper.GetPing)
}

To implement this HTTP server, we need to write the following code in our api/impl.go:

import (
"net/http""github.com/gin-gonic/gin"
)
// optional code omittedtypeServerstruct{}
funcNewServer() Server {
returnServer{}
}
// (GET /ping)func (Server) GetPing(ctx*gin.Context) {
resp:=Pong{
Ping: "pong",
}
ctx.JSON(http.StatusOK, resp)
}

Now we've got our implementation, we can then write the following code to wire it up and get a running server:

import (
"log""net/http""github.com/deepmap/oapi-codegen/v2/examples/minimal-server/gin/api""github.com/gin-gonic/gin"
)
funcmain() {
// create a type that satisfies the `api.ServerInterface`, which contains an implementation of every operation from the generated codeserver:=api.NewServer()
r:=gin.Default()
api.RegisterHandlers(r, server)
// And we serve HTTP until the world ends.s:=&http.Server{
Handler: r,
Addr: "0.0.0.0:8080",
}
// And we serve HTTP until the world ends.log.Fatal(s.ListenAndServe())
}

Note

This doesn't include validation of incoming requests.

Iris server

For instance, let's take this straightforward specification:

openapi: "3.0.0"info:
version: 1.0.0title: Minimal ping API serverpaths:
/ping:
get:
responses:
'200':
description: pet responsecontent:
application/json:
schema:
$ref: '#/components/schemas/Pong'components:
schemas:
# base typesPong:
type: objectrequired:
- pingproperties:
ping:
type: stringexample: pong

This then generates code such as:

// Pong defines model for Pong.typePongstruct {
Pingstring`json:"ping"`
}
// ServerInterface represents all server handlers.typeServerInterfaceinterface {
// (GET /ping)GetPing(ctx iris.Context)
}
// RegisterHandlers creates http.Handler with routing matching OpenAPI spec.funcRegisterHandlers(router*iris.Application, siServerInterface) {
RegisterHandlersWithOptions(router, si, IrisServerOptions{})
}
// RegisterHandlersWithOptions creates http.Handler with additional optionsfuncRegisterHandlersWithOptions(router*iris.Application, siServerInterface, optionsIrisServerOptions) {
// ...router.Get(options.BaseURL+"/ping", wrapper.GetPing)
router.Build()
}

To implement this HTTP server, we need to write the following code in our api/impl.go:

import (
"net/http""github.com/kataras/iris/v12"
)
// optional code omittedtypeServerstruct{}
funcNewServer() Server {
returnServer{}
}
// (GET /ping)func (Server) GetPing(ctx iris.Context) {
resp:=Pong{
Ping: "pong",
}
ctx.StatusCode(http.StatusOK)
_=ctx.JSON(resp)
}

Now we've got our implementation, we can then write the following code to wire it up and get a running server:

import (
"log""github.com/deepmap/oapi-codegen/v2/examples/minimal-server/iris/api""github.com/kataras/iris/v12"
)
funcmain() {
// create a type that satisfies the `api.ServerInterface`, which contains an implementation of every operation from the generated codeserver:=api.NewServer()
i:=iris.Default()
api.RegisterHandlers(i, server)
// And we serve HTTP until the world ends.log.Fatal(i.Listen("0.0.0.0:8080"))
}

Note

This doesn't include validation of incoming requests.

Strict server

oapi-codegen also supports generating a server that is much more strict with the contract that the implementer requires, and takes inspiration from server-side code generation for RPC servers.

This takes the boilerplate reduction from the non-strict servers and adds additional boilerplate reduction, allowing you to make the following changes to your function signatures:

-FindPets(w http.ResponseWriter, r *http.Request, params FindPetsParams)+FindPets(ctx context.Context, request FindPetsRequestObject) (FindPetsResponseObject, error)

This is the highest level of strictness that oapi-codegen supports right now, and it's a good idea to start with this if you want the most guardrails to simplify developing your APIs.

The strict server has support for:

multiple request/response media types and status codes on a given operation
first-class support for multipart/form-data and application/x-www-form-urlencoded requests
returning an HTTP 500 Internal Server Error, when an error is returned from a function
automagic (un)marshalling of request/responses, and setting content-type and HTTP status codes on responses
binding request values to a struct, a multipart.Reader or providing a io.Reader

You can see a little more detail of the generated code in the "What does it look like" section.

Note

To configure the strict server generation, you must specify another server to be generated. For instance:

# yaml-language-server: $schema=https://raw.githubusercontent.com/deepmap/oapi-codegen/HEAD/configuration-schema.jsonpackage: apigenerate:
# NOTE another server must be added!chi-server: truestrict-server: trueoutput: server.gen.go

Note

This doesn't include validation of incoming requests.

Generating API clients

As well as generating the server-side boilerplate, oapi-codegen can also generate API clients.

This aims to be an API client that can be used to interact with the methods of the API, and is perfectly suited for production usage.

However, if you were looking for a slightly more SDK-style approach, or a mix of generated tests and/or documentation, this API client may not be for you, and you may want to look at alternate tooling.

For instance, given an api.yaml:

openapi: "3.0.0"info:
version: 1.0.0title: Generate modelspaths:
/client:
get:
operationId: getClientresponses:
200:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientType"put:
operationId: updateClientresponses:
400:
content:
application/json:
schema:
type: objectproperties:
code:
type: stringrequired:
- codecomponents:
schemas:
ClientType:
type: objectrequired:
- nameproperties:
name:
type: string# NOTE that this is not generated by default because it's not referenced. If you want it, you need to use the following YAML configuration:## output-options:# skip-prune: trueUnreferenced:
type: objectrequired:
- idproperties:
id:
type: integer

And a cfg.yaml:

# yaml-language-server: $schema=https://raw.githubusercontent.com/deepmap/oapi-codegen/HEAD/configuration-schema.jsonpackage: clientoutput: client.gen.gogenerate:
models: trueclient: true

And a generate.go:

package client
//go:generate go run github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen -config cfg.yaml api.yaml

This would then generate:

package client
// ...// ClientType defines model for ClientType.typeClientTypestruct {
Namestring`json:"name"`
}
// ...// Client which conforms to the OpenAPI3 specification for this service.typeClientstruct {
// The endpoint of the server conforming to this interface, with scheme,// https://api.deepmap.com for example. This can contain a path relative// to the server, such as https://api.deepmap.com/dev-test, and all the// paths in the swagger spec will be appended to the server.Serverstring// Doer for performing requests, typically a *http.Client with any// customized settings, such as certificate chains.ClientHttpRequestDoer// A list of callbacks for modifying requests which are generated before sending over// the network.RequestEditors []RequestEditorFn
}
// ...// The interface specification for the client above.typeClientInterfaceinterface {
// GetClient requestGetClient(ctx context.Context, reqEditors...RequestEditorFn) (*http.Response, error)
// UpdateClient requestUpdateClient(ctx context.Context, reqEditors...RequestEditorFn) (*http.Response, error)
}
// ...// ClientWithResponsesInterface is the interface specification for the client with responses above.typeClientWithResponsesInterfaceinterface {
// GetClientWithResponse requestGetClientWithResponse(ctx context.Context, reqEditors...RequestEditorFn) (*GetClientResponse, error)
// UpdateClientWithResponse requestUpdateClientWithResponse(ctx context.Context, reqEditors...RequestEditorFn) (*UpdateClientResponse, error)
}
typeGetClientResponsestruct {
Body []byteHTTPResponse*http.ResponseJSON200*ClientType
}
// ...

With this generated client, it is then possible to construct and utilise the client, for instance:

package client_test
import (
"context""fmt""log""net/http""github.com/deepmap/oapi-codegen/v2/examples/client"
)
funcTestClient_canCall() {
// custom HTTP clienthc:= http.Client{}
// with a raw http.Response
{
c, err:=client.NewClient("http://localhost:1234", client.WithHTTPClient(&hc))
iferr!=nil {
log.Fatal(err)
}
resp, err:=c.GetClient(context.TODO())
iferr!=nil {
log.Fatal(err)
}
ifresp.StatusCode!=http.StatusOK {
log.Fatalf("Expected HTTP 200 but received %d", resp.StatusCode)
}
}
// or to get a struct with the parsed response body
{
c, err:=client.NewClientWithResponses("http://localhost:1234", client.WithHTTPClient(&hc))
iferr!=nil {
log.Fatal(err)
}
resp, err:=c.GetClientWithResponse(context.TODO())
iferr!=nil {
log.Fatal(err)
}
ifresp.StatusCode() !=http.StatusOK {
log.Fatalf("Expected HTTP 200 but received %d", resp.StatusCode())
}
fmt.Printf("resp.JSON200: %v\n", resp.JSON200)
}
}

Generating API models

If you're looking to only generate the models for interacting with a remote service, for instance if you need to hand-roll the API client for whatever reason, you can do this as-is.

Tip

Try to define as much as possible within the #/components/schemas object, as oapi-codegen will generate all the types here.

Although we can generate some types based on inline definitions in i.e. a path's response type, it isn't always possible to do this, or if it is generated, can be a little awkward to work with as it may be defined as an anonymous struct.

For instance, given an api.yaml:

openapi: "3.0.0"info:
version: 1.0.0title: Generate modelspaths:
/client:
get:
operationId: getClientresponses:
200:
content:
application/json:
schema:
# NOTE that Client is generated here, because it's within #/components/schemas$ref: "#/components/schemas/Client"put:
operationId: updateClientresponses:
400:
content:
application/json:
# NOTE that this anonymous object is /not/ generated because it's an anonymous, but would be generated if using `generate: client`# See https://github.com/deepmap/oapi-codegen/issues/1512schema:
type: objectproperties:
code:
type: stringrequired:
- codecomponents:
schemas:
Client:
type: objectrequired:
- nameproperties:
name:
type: string# NOTE that this is not generated by default because it's not referenced. If you want it, you need to use the following YAML configuration:## output-options:# skip-prune: trueUnreferenced:
type: objectrequired:
- idproperties:
id:
type: integer

And a cfg.yaml:

# yaml-language-server: $schema=https://raw.githubusercontent.com/deepmap/oapi-codegen/HEAD/configuration-schema.jsonpackage: onlymodelsoutput: only-models.gen.gogenerate:
models: true

And a generate.go:

package onlymodels
//go:generate go run github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen -config cfg.yaml api.yaml

This would then generate:

package onlymodels
// Client defines model for Client.typeClientstruct {
Namestring`json:"name"`
}

If you wish to also generate the Unreferenced type, you would need the following cfg.yaml:

# yaml-language-server: $schema=https://raw.githubusercontent.com/deepmap/oapi-codegen/HEAD/configuration-schema.jsonpackage: onlymodelsoutput: only-models.gen.gogenerate:
models: trueoutput-options:
# NOTE that this is only required for the `Unreferenced` typeskip-prune: true

For a complete example see examples/only-models.

Splitting large OpenAPI specs across multiple packages (aka "Import Mapping" or "external references")

When you've got a large OpenAPI specification, you may find it useful to split the contents of the spec across multiple files, using external references, such as:

components:
schemas:
User:
$ref: '../common/api.yaml#/components/schemas/User'

This is supported by oapi-codegen, through the ability to perform "Import Mapping".

For instance, let's say that we have a large API, which has a user-facing API and an admin API, both of which use a common set of API models.

In this case, we may have an Admin API that looks like:

# admin/api.yamlopenapi: "3.0.0"info:
version: 1.0.0title: Admin APIdescription: The admin-only portion of the API, which has its own separate OpenAPI spectags:
- name: admindescription: Admin API endpoints
- name: userdescription: API endpoint that pertains to user datapaths:
/admin/user/{id}:
get:
tags:
- admin
- usersummary: Get a user's detailsoperationId: getUserByIdparameters:
- name: idin: pathrequired: trueschema:
type: stringformat: uuidresponses:
200:
description: Successcontent:
application/json:
schema:
$ref: '#/components/schemas/User'components:
schemas:
User:
$ref: '../common/api.yaml#/components/schemas/User'

This references the common spec:

# common/api.yamlcomponents:
schemas:
User:
type: objectadditionalProperties: falseproperties:
name:
type: stringrequired:
- name

And finally we have our configuration file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/deepmap/oapi-codegen/HEAD/configuration-schema.json# admin/cfg.yamlpackage: adminoutput: server.gen.gogenerate:
models: truechi-server: trueoutput-options:
# to make sure that all types are generatedskip-prune: true# NOTE that this won't work, as it's missing `import-mapping`

If we were to run oapi-codegen, this will fail with the following error

error generating code: error creating operation definitions: error generating response definitions: error generating request body definition: error turning reference (../common/api.yaml#/components/schemas/User) into a Go type: unrecognized external reference '../common/api.yaml'; please provide the known import for this reference using option --import-mapping

This is because oapi-codegen requires:

# yaml-language-server: $schema=https://raw.githubusercontent.com/deepmap/oapi-codegen/HEAD/configuration-schema.jsonpackage: adminoutput: server.gen.gogenerate:
models: truechi-server: trueoutput-options:
# to make sure that all types are generatedskip-prune: trueimport-mapping:
# for a given file/URL that is $ref'd, point `oapi-codegen` to the Go package that this spec is generated into, to perform Go package imports../common/api.yaml: github.com/deepmap/oapi-codegen/v2/examples/import-mapping/common

This will then generate the following code:

package admin
import (
// ...
externalRef0 "github.com/deepmap/oapi-codegen/v2/examples/import-mapping/common"
)
// User defines model for User.typeUser= externalRef0.User

If you don't want to do this, an alternate option is to bundle your multiple OpenAPI files into a single spec.

Check out the import-mapping example for the full code.

Generating Nullable types

It's possible that you want to be able to determine whether a field isn't sent, is sent as null or has a value.

For instance, if you had the following OpenAPI property:

S:
type: objectproperties:
Field:
type: stringnullable: truerequired: []

The default behaviour in oapi-codegen is to generate:

typeSstruct {
Field*string`json:"field,omitempty"`
}

However, you lose the ability to understand the three cases, as there's no way to distinguish two of the types from each other:

is this field not sent? (Can be checked with S.Field == nil)
is this field null? (Can be checked with S.Field == nil)
does this field have a value? (S.Field != nil && *S.Field == "123")

As of oapi-codegenv2.1.0 it is now possible to represent this with the nullable.Nullable type from our new library, oapi-codegen/nullable.

If you configure your generator's Output Options to opt-in to this behaviour, as so:

output-options:
nullable-type: true

You will now receive the following output:

typeSstruct {
// note that there's no pointer here, just `omitempty`Field nullable.Nullable[string] `json:"field,omitempty"`
}

OpenAPI extensions

As well as the core OpenAPI support, we also support the following OpenAPI extensions, as denoted by the OpenAPI Specification Extensions.

Extension	Description	Example usage
`x-go-type` `x-go-type-import`	Override the generated type definition (and optionally, add an import from another package)	Details Using the `x-go-type` (and optionally, `x-go-type-import` when you need to import another package) allows overriding the type that `oapi-codegen` determined the generated type should be. We can see this at play with the following schemas: components: schemas: Client: type: objectrequired: - nameproperties: name: type: stringid: type: numberClientWithExtension: type: objectrequired: - nameproperties: name: type: string# this is a bit of a contrived example, as you could instead use# `format: uuid` but it explains how you'd do this when there may be# a clash, for instance if you already had a `uuid` package that was# being imported, or ...x-go-type: googleuuid.UUIDx-go-type-import: path: github.com/google/uuidname: googleuuidid: type: number# ... this is also a bit of a contrived example, as you could use# `type: integer` but in the case that you know better than what# oapi-codegen is generating, like so:x-go-type: int64 From here, we now get two different models: // Client defines model for Client.typeClientstruct { Idfloat32`json:"id,omitempty"`Namestring`json:"name"` } // ClientWithExtension defines model for ClientWithExtension.typeClientWithExtensionstruct { Idint64`json:"id,omitempty"`Name googleuuid.UUID`json:"name"` } You can see this in more detail in the example code.
`x-go-type-skip-optional-pointer`	Do not add a pointer type for optional fields in structs	Details By default, `oapi-codegen` will generate a pointer for optional fields. Using the `x-go-type-skip-optional-pointer` extension allows omitting that pointer. We can see this at play with the following schemas: components: schemas: Client: type: objectrequired: - nameproperties: name: type: stringid: type: numberClientWithExtension: type: objectrequired: - nameproperties: name: type: stringid: type: numberx-go-type-skip-optional-pointer: true From here, we now get two different models: // Client defines model for Client.typeClientstruct { Id*float32`json:"id,omitempty"`Namestring`json:"name"` } // ClientWithExtension defines model for ClientWithExtension.typeClientWithExtensionstruct { Idfloat32`json:"id,omitempty"`Namestring`json:"name"` } You can see this in more detail in the example code.
`x-go-name`	Override the generated name of a field or a type	Details By default, `oapi-codegen` will attempt to generate the name of fields and types in as best a way it can. However, sometimes, the name doesn't quite fit what your codebase standards are, or the intent of the field, so you can override it with `x-go-name`. We can see this at play with the following schemas: openapi: "3.0.0"info: version: 1.0.0title: x-go-namecomponents: schemas: Client: type: objectrequired: - nameproperties: name: type: stringid: type: numberClientWithExtension: type: object# can be used on a typex-go-name: ClientRenamedByExtensionrequired: - nameproperties: name: type: stringid: type: number# or on a fieldx-go-name: AccountIdentifier From here, we now get two different models: // Client defines model for Client.typeClientstruct { Idfloat32`json:"id,omitempty"`Namestring`json:"name"` } // ClientRenamedByExtension defines model for ClientWithExtension.typeClientRenamedByExtensionstruct { AccountIdentifierfloat32`json:"id,omitempty"`Namestring`json:"name"` } You can see this in more detail in the example code.
`x-go-type-name`	Override the generated name of a type	Details [!NOTE] Notice that this is subtly different to the `x-go-name`, which also applies to fields within `struct`s. By default, `oapi-codegen` will attempt to generate the name of types in as best a way it can. However, sometimes, the name doesn't quite fit what your codebase standards are, or the intent of the field, so you can override it with `x-go-name`. We can see this at play with the following schemas: openapi: "3.0.0"info: version: 1.0.0title: x-go-type-namecomponents: schemas: Client: type: objectrequired: - nameproperties: name: type: stringid: type: numberClientWithExtension: type: objectx-go-type-name: ClientRenamedByExtensionrequired: - nameproperties: name: type: stringid: type: number# NOTE attempting a `x-go-type-name` here is a no-op, as we're not producing a _type_ only a _field_x-go-type-name: ThisWillNotBeUsed From here, we now get two different models and a type alias: // Client defines model for Client.typeClientstruct { Idfloat32`json:"id,omitempty"`Namestring`json:"name"` } // ClientWithExtension defines model for ClientWithExtension.typeClientWithExtension=ClientRenamedByExtension// ClientRenamedByExtension defines model for .typeClientRenamedByExtensionstruct { Idfloat32`json:"id,omitempty"`Namestring`json:"name"` } You can see this in more detail in the example code.
`x-omitempty`	Force the presence of the JSON tag `omitempty` on a field	Details In a case that you may want to add the JSON struct tag `omitempty` to types that don't have one generated by default - for instance a required field - you can use the `x-omitempty` extension. We can see this at play with the following schemas: openapi: "3.0.0"info: version: 1.0.0title: x-omitemptycomponents: schemas: Client: type: objectrequired: - nameproperties: name: type: stringid: type: numberClientWithExtension: type: objectrequired: - nameproperties: name: type: string# for some reason, you may want this behaviour, even though it's a required fieldx-omitempty: trueid: type: number From here, we now get two different models: // Client defines model for Client.typeClientstruct { Idfloat32`json:"id,omitempty"`Namestring`json:"name"` } // ClientWithExtension defines model for ClientWithExtension.typeClientWithExtensionstruct { Idfloat32`json:"id,omitempty"`Namestring`json:"name,omitempty"` } Notice that the `ComplexField` is still generated in full, but the type will then be ignored with JSON marshalling. You can see this in more detail in the example code.
`x-go-json-ignore`	When (un)marshaling JSON, ignore field(s)	Details By default, `oapi-codegen` will generate `json:"..."` struct tags for all fields in a struct, so JSON (un)marshaling works. However, sometimes, you want to omit fields, which can be done with the `x-go-json-ignore` extension. We can see this at play with the following schemas: openapi: "3.0.0"info: version: 1.0.0title: x-go-json-ignorecomponents: schemas: Client: type: objectrequired: - nameproperties: name: type: stringcomplexField: type: objectproperties: name: type: stringaccountName: type: string# ...ClientWithExtension: type: objectrequired: - nameproperties: name: type: stringcomplexField: type: objectproperties: name: type: stringaccountName: type: string# ...x-go-json-ignore: true From here, we now get two different models: // Client defines model for Client.typeClientstruct { ComplexFieldstruct { AccountNamestring`json:"accountName,omitempty"`Namestring`json:"name,omitempty"` } `json:"complexField,omitempty"`Namestring`json:"name"` } // ClientWithExtension defines model for ClientWithExtension.typeClientWithExtensionstruct { ComplexFieldstruct { AccountNamestring`json:"accountName,omitempty"`Namestring`json:"name,omitempty"` } `json:"-"`Namestring`json:"name"` } Notice that the `ComplexField` is still generated in full, but the type will then be ignored with JSON marshalling. You can see this in more detail in the example code.
`x-oapi-codegen-extra-tags`	Generate arbitrary struct tags to fields	Details If you're making use of a field's struct tags to i.e. apply validation, decide whether something should be logged, etc, you can use `x-oapi-codegen-extra-tags` to set additional tags for your generated types. We can see this at play with the following schemas: openapi: "3.0.0"info: version: 1.0.0title: x-oapi-codegen-extra-tagscomponents: schemas: Client: type: objectrequired: - name - idproperties: name: type: stringid: type: numberClientWithExtension: type: objectrequired: - name - idproperties: name: type: stringid: type: numberx-oapi-codegen-extra-tags: validate: "required,min=1,max=256"safe-to-log: "true"gorm: primarykey From here, we now get two different models: // Client defines model for Client.typeClientstruct { Idfloat32`json:"id"`Namestring`json:"name"` } // ClientWithExtension defines model for ClientWithExtension.typeClientWithExtensionstruct { Idfloat32`gorm:"primarykey" json:"id" safe-to-log:"true" validate:"required,min=1,max=256"`Namestring`json:"name"` } You can see this in more detail in the example code.
`x-enum-varnames` / `x-enumNames`	Override generated variable names for enum constants	Details When consuming an enum value from an external system, the name may not produce a nice variable name. Using the `x-enum-varnames` extension allows overriding the name of the generated variable names. We can see this at play with the following schemas: openapi: "3.0.0"info: version: 1.0.0title: x-enumNames and x-enum-varnamescomponents: schemas: ClientType: type: stringenum: - ACT - EXPClientTypeWithNamesExtension: type: stringenum: - ACT - EXPx-enumNames: - Active - ExpiredClientTypeWithVarNamesExtension: type: stringenum: - ACT - EXPx-enum-varnames: - Active - Expired From here, we now get two different forms of the same enum definition. // Defines values for ClientType.const ( ACTClientType="ACT"EXPClientType="EXP" ) // ClientType defines model for ClientType.typeClientTypestring// Defines values for ClientTypeWithExtension.const ( ActiveClientTypeWithExtension="ACT"ExpiredClientTypeWithExtension="EXP" ) // ClientTypeWithExtension defines model for ClientTypeWithExtension.typeClientTypeWithExtensionstring You can see this in more detail in the example code.
`x-deprecated-reason`	Add a GoDoc deprecation warning to a type	Details When an OpenAPI type is deprecated, a deprecation warning can be added in the GoDoc using `x-deprecated-reason`. We can see this at play with the following schemas: openapi: "3.0.0"info: version: 1.0.0title: x-deprecated-reasoncomponents: schemas: Client: type: objectrequired: - nameproperties: name: type: stringid: type: numberClientWithExtension: type: objectrequired: - nameproperties: name: type: stringdeprecated: truex-deprecated-reason: Don't use because reasonsid: type: number# NOTE that this doesn't generate, as no `deprecated: true` is setx-deprecated-reason: NOTE you shouldn't see this, as you've not deprecated this field From here, we now get two different forms of the same enum definition. // Client defines model for Client.typeClientstruct { Idfloat32`json:"id,omitempty"`Namestring`json:"name"` } // ClientWithExtension defines model for ClientWithExtension.typeClientWithExtensionstruct { Idfloat32`json:"id,omitempty"`// Deprecated: Don't use because reasonsNamestring`json:"name"` } Notice that because we've not set `deprecated: true` to the `name` field, it doesn't generate a deprecation warning. You can see this in more detail in the example code.
`x-order`	Explicitly order struct fields	Details Whether you like certain fields being ordered before others, or you want to perform more efficient packing of your structs, the `x-order` extension is here for you. Note that `x-order` is 1-indexed - `x-order: 0` is not a valid value. When an OpenAPI type is deprecated, a deprecation warning can be added in the GoDoc using `x-deprecated-reason`. We can see this at play with the following schemas: openapi: "3.0.0"info: version: 1.0.0title: x-ordercomponents: schemas: Client: type: objectrequired: - nameproperties: a_name: type: stringid: type: numberClientWithExtension: type: objectrequired: - nameproperties: a_name: type: stringx-order: 2id: type: numberx-order: 1 From here, we now get two different forms of the same type definition. // Client defines model for Client.typeClientstruct { ANamestring`json:"a_name,omitempty"`Idfloat32`json:"id,omitempty"` } // ClientWithExtension defines model for ClientWithExtension.typeClientWithExtensionstruct { Idfloat32`json:"id,omitempty"`ANamestring`json:"a_name,omitempty"` } You can see this in more detail in the example code.

Request/response validation middleware

The generated code that oapi-codegen produces has some validation for some incoming data, such as checking for required headers, and when using the strict server you get some more validation around the correct usage of the response types.

However, this leaves a lot of validation that needs to be done, which can be tedious to hand-write this logic, especially for large or complex OpenAPI specifications.

To simplify this, we use a middleware, which provides the request validation. The middleware you want to use depends on the server you're using:

Server	Middleware library
Chi	nethttp-middleware
Echo	echo-middleware
Fiber	fiber-middleware
Gin	gin-middleware
gorilla/mux	nethttp-middleware
Iris	iris-middleware
1.22+ `net/http`	nethttp-middleware

Note

It is not currently possible to validate the HTTP response with a middleware.

Note

We're also exploring the use of libopenapi-validator for request/response validation middleware

Implementing security

If you're using a specification with Security Schemes and Security Requirements, you'll want to authenticate and authorize requests.

On the server

Note

Out-of-the-box, the server-side code generated by oapi-codegen does not provide security validation.

To perform authentication, you will need to use the validation middleware.

In the future, we plan to implement server-side validation in the generated code

To see how this can work, check out the authenticated API example.

On the client

With a generated client, you'll want to use the client's generated WithRequestEditorFn function to pass in a given request editor RequestEditorFn.

For instance:

import (
"context""fmt""log""github.com/deepmap/oapi-codegen/v2/pkg/securityprovider"
)
funcmain() {
basicAuth, err:=securityprovider.NewSecurityProviderBasicAuth("my_user", "my_pass")
iferr!=nil {
log.Fatal(err)
}
client, err:=NewClient("https://....", WithRequestEditorFn(basicAuth.Intercept))
iferr!=nil {
log.Fatal(err)
}
resp, err:=client.GetClient(context.TODO())
iferr!=nil {
log.Fatal(err)
}
fmt.Printf("resp.StatusCode: %v\n", resp.StatusCode)
}

Notice that we're using a pre-built provider from the pkg/securityprovider package, which has some inbuilt support for other types of authentication, too.

Custom code generation

It is possible to extend the inbuilt code generation from oapi-codegen using Go's text/templates.

You can specify, through your configuration file, the output-options.user-templates setting to override the inbuilt templates and use a user-defined template.

Note

Filenames given to the user-templates configuration must exactly match the filename that oapi-codegen is looking for

Local paths

Within your configuration file, you can specify relative or absolute paths to a file to reference for the template, such as:

# yaml-language-server: $schema=https://raw.githubusercontent.com/deepmap/oapi-codegen/HEAD/configuration-schema.json# ...output-options:
user-templates:
client-with-responses.tmpl: ./custom-template.tmpladditional-properties.tmpl: /tmp/foo.bartypedef.tmpl: no-prefix.tmpl

[!WARN] We do not interpolate ~ or $HOME (or other environment variables) in paths given

HTTPS paths

It is also possible to use HTTPS URLs.

Warning

Although possible, this does lead to oapi-codegen executions not necessarily being reproducible. It's recommended to vendor (copy) the OpenAPI spec into your codebase and reference it locally

See this blog post for an example of how to use GitHub Actions to manage the updates of files across repos

This will be disabled by default (but possible to turn back on via configuration) in the future

To use it, you can use the following configuration:

# yaml-language-server: $schema=https://raw.githubusercontent.com/deepmap/oapi-codegen/HEAD/configuration-schema.json# ...output-options:
user-templates:
# The following are referencing a version of the default client-with-responses.tmpl file, but loaded in through GitHub's raw.githubusercontent.com. The general form to use raw.githubusercontent.com is as follows https://raw.githubusercontent.com/<username>/<project>/<commitish>/path/to/template/template.tmpl# Alternatively using raw.githubusercontent.com with a hashclient-with-responses.tmpl: https://raw.githubusercontent.com/deepmap/oapi-codegen/ad5eada4f3ccc28a88477cef62ea21c17fc8aa01/pkg/codegen/templates/client-with-responses.tmpl# Alternatively using raw.githubusercontent.com with a tagclient-with-responses.tmpl: https://raw.githubusercontent.com/deepmap/oapi-codegen/v2.1.0/pkg/codegen/templates/client-with-responses.tmpl# Alternatively using raw.githubusercontent.com with a branchclient-with-responses.tmpl: https://raw.githubusercontent.com/deepmap/oapi-codegen/master/pkg/codegen/templates/client-with-responses.tmpl

Warning

If using URLs that pull locations from a Git repo, such as raw.githubusercontent.com, it is strongly encouraged to use a tag or a raw commit hash instead of a branch like main. Tracking a branch can lead to unexpected API drift, and loss of the ability to reproduce a build.

Inline template

It's also possible to set the templates inline in the configuration file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/deepmap/oapi-codegen/HEAD/configuration-schema.json# ...output-options:
user-templates:
# NOTE the use of the `|` (pipe symbol) here to denote that this is a# multi-line statement that should preserve newlines. More reading:# https://stackoverflow.com/a/18708156/2257038 and# https://stackoverflow.com/a/15365296/2257038client-with-responses.tmpl: | // ClientWithResponses builds on ClientInterface to offer response payloads type ClientWithResponses struct { ClientInterface } ...

Using the Go package

Alternatively, you are able to use the underlying code generation as a package, which will be documented in the future.

Additional Properties (`additionalProperties`)

OpenAPI Schemas 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, OpenAPI defines that the additionalProperties field is assumed to be true.

For simplicity, and to remove a fair bit of duplication and boilerplate, oapi-codegen decides to ignore the implicit additionalProperties: true, and instead requires you to specify the additionalProperties key to generate the boilerplate.

Note

In the future this will be possible to disable this functionality, and honour the implicit additionalProperties: true

Below you can see some examples of how additionalProperties affects the generated code.

Implicit `additionalProperties: true` / no `additionalProperties` set

components:
schemas:
Thing:
type: objectrequired:
- idproperties:
id:
type: integer# implicit additionalProperties: true

Will generate:

// Thing defines model for Thing.typeThingstruct {
Idint`json:"id"`
}
// with no generated boilerplate nor the `AdditionalProperties` field

Explicit `additionalProperties: true`

components:
schemas:
Thing:
type: objectrequired:
- idproperties:
id:
type: integer# explicit trueadditionalProperties: true

Will generate:

// Thing defines model for Thing.typeThingstruct {
Idint`json:"id"`AdditionalPropertiesmap[string]interface{} `json:"-"`
}
// with generated boilerplate below

Boilerplate

// Getter for additional properties for Thing. Returns the specified// element and whether it was foundfunc (aThing) Get(fieldNamestring) (valueinterface{}, foundbool) {
ifa.AdditionalProperties!=nil {
value, found=a.AdditionalProperties[fieldName]
}
return
}
// Setter for additional properties for Thingfunc (a*Thing) Set(fieldNamestring, valueinterface{}) {
ifa.AdditionalProperties==nil {
a.AdditionalProperties=make(map[string]interface{})
}
a.AdditionalProperties[fieldName] =value
}
// Override default JSON handling for Thing to handle AdditionalPropertiesfunc (a*Thing) UnmarshalJSON(b []byte) error {
object:=make(map[string]json.RawMessage)
err:=json.Unmarshal(b, &object)
iferr!=nil {
returnerr
}
ifraw, found:=object["id"]; found {
err=json.Unmarshal(raw, &a.Id)
iferr!=nil {
returnfmt.Errorf("error reading 'id': %w", err)
}
delete(object, "id")
}
iflen(object) !=0 {
a.AdditionalProperties=make(map[string]interface{})
forfieldName, fieldBuf:=rangeobject {
varfieldValinterface{}
err:=json.Unmarshal(fieldBuf, &fieldVal)
iferr!=nil {
returnfmt.Errorf("error unmarshaling field %s: %w", fieldName, err)
}
a.AdditionalProperties[fieldName] =fieldVal
}
}
returnnil
}
// Override default JSON handling for Thing to handle AdditionalPropertiesfunc (aThing) MarshalJSON() ([]byte, error) {
varerrerrorobject:=make(map[string]json.RawMessage)
object["id"], err=json.Marshal(a.Id)
iferr!=nil {
returnnil, fmt.Errorf("error marshaling 'id': %w", err)
}
forfieldName, field:=rangea.AdditionalProperties {
object[fieldName], err=json.Marshal(field)
iferr!=nil {
returnnil, fmt.Errorf("error marshaling '%s': %w", fieldName, err)
}
}
returnjson.Marshal(object)
}

`additionalProperties` as `integer`s

components:
schemas:
Thing:
type: objectrequired:
- idproperties:
id:
type: integer# simple typeadditionalProperties:
type: integer

Will generate:

// Thing defines model for Thing.typeThingstruct {
Idint`json:"id"`AdditionalPropertiesmap[string]int`json:"-"`
}
// with generated boilerplate below

Boilerplate

// Getter for additional properties for Thing. Returns the specified// element and whether it was foundfunc (aThing) Get(fieldNamestring) (valueint, foundbool) {
ifa.AdditionalProperties!=nil {
value, found=a.AdditionalProperties[fieldName]
}
return
}
// Setter for additional properties for Thingfunc (a*Thing) Set(fieldNamestring, valueint) {
ifa.AdditionalProperties==nil {
a.AdditionalProperties=make(map[string]int)
}
a.AdditionalProperties[fieldName] =value
}
// Override default JSON handling for Thing to handle AdditionalPropertiesfunc (a*Thing) UnmarshalJSON(b []byte) error {
object:=make(map[string]json.RawMessage)
err:=json.Unmarshal(b, &object)
iferr!=nil {
returnerr
}
ifraw, found:=object["id"]; found {
err=json.Unmarshal(raw, &a.Id)
iferr!=nil {
returnfmt.Errorf("error reading 'id': %w", err)
}
delete(object, "id")
}
iflen(object) !=0 {
a.AdditionalProperties=make(map[string]int)
forfieldName, fieldBuf:=rangeobject {
varfieldValinterr:=json.Unmarshal(fieldBuf, &fieldVal)
iferr!=nil {
returnfmt.Errorf("error unmarshaling field %s: %w", fieldName, err)
}
a.AdditionalProperties[fieldName] =fieldVal
}
}
returnnil
}
// Override default JSON handling for Thing to handle AdditionalPropertiesfunc (aThing) MarshalJSON() ([]byte, error) {
varerrerrorobject:=make(map[string]json.RawMessage)
object["id"], err=json.Marshal(a.Id)
iferr!=nil {
returnnil, fmt.Errorf("error marshaling 'id': %w", err)
}
forfieldName, field:=rangea.AdditionalProperties {
object[fieldName], err=json.Marshal(field)
iferr!=nil {
returnnil, fmt.Errorf("error marshaling '%s': %w", fieldName, err)
}
}
returnjson.Marshal(object)
}

`additionalProperties` with an object

components:
schemas:
Thing:
type: objectrequired:
- idproperties:
id:
type: integer# objectadditionalProperties:
type: objectproperties:
foo:
type: string

Will generate:

// Thing defines model for Thing.typeThingstruct {
Idint`json:"id"`AdditionalPropertiesmap[string]struct {
Foo*string`json:"foo,omitempty"`
} `json:"-"`
}
// with generated boilerplate below

Boilerplate

// Getter for additional properties for Thing. Returns the specified// element and whether it was foundfunc (aThing) Get(fieldNamestring) (valuestruct {
Foo*string`json:"foo,omitempty"`
}, foundbool) {
ifa.AdditionalProperties!=nil {
value, found=a.AdditionalProperties[fieldName]
}
return
}
// Setter for additional properties for Thingfunc (a*Thing) Set(fieldNamestring, valuestruct {
Foo*string`json:"foo,omitempty"`
}) {
ifa.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 AdditionalPropertiesfunc (a*Thing) UnmarshalJSON(b []byte) error {
object:=make(map[string]json.RawMessage)
err:=json.Unmarshal(b, &object)
iferr!=nil {
returnerr
}
ifraw, found:=object["id"]; found {
err=json.Unmarshal(raw, &a.Id)
iferr!=nil {
returnfmt.Errorf("error reading 'id': %w", err)
}
delete(object, "id")
}
iflen(object) !=0 {
a.AdditionalProperties=make(map[string]struct {
Foo*string`json:"foo,omitempty"`
})
forfieldName, fieldBuf:=rangeobject {
varfieldValstruct {
Foo*string`json:"foo,omitempty"`
}
err:=json.Unmarshal(fieldBuf, &fieldVal)
iferr!=nil {
returnfmt.Errorf("error unmarshaling field %s: %w", fieldName, err)
}
a.AdditionalProperties[fieldName] =fieldVal
}
}
returnnil
}
// Override default JSON handling for Thing to handle AdditionalPropertiesfunc (aThing) MarshalJSON() ([]byte, error) {
varerrerrorobject:=make(map[string]json.RawMessage)
object["id"], err=json.Marshal(a.Id)
iferr!=nil {
returnnil, fmt.Errorf("error marshaling 'id': %w", err)
}
forfieldName, field:=rangea.AdditionalProperties {
object[fieldName], err=json.Marshal(field)
iferr!=nil {
returnnil, fmt.Errorf("error marshaling '%s': %w", fieldName, err)
}
}
returnjson.Marshal(object)
}

Changing the names of generated types

As of oapi-codegen v2.2.0, it is now possible to use the output-options configuration's name-normalizer to define the logic for how to convert an OpenAPI name (i.e. an Operation ID or a Schema name) and construct a Go type name.

Example, using default configuration

By default, oapi-codegen will perform camel-case conversion, so for a spec such as:

openapi: "3.0.0"info:
version: 1.0.0title: Example code for the `name-normalizer` output optionpaths:
/api/pets/{petId}:
get:
summary: Get pet given identifier.operationId: getHttpPetparameters:
- name: petIdin: pathrequired: trueschema:
type: stringresponses:
'200':
description: valid petcontent:
application/json:
schema:
$ref: '#/components/schemas/Pet'components:
schemas:
Pet:
type: objectrequired:
- uuid
- nameproperties:
uuid:
type: stringdescription: The pet uuid.name:
type: stringdescription: The name of the pet.Error:
required:
- code
- messageproperties:
code:
type: integerformat: int32description: Error codemessage:
type: stringdescription: Error messageOneOf2things:
description: "Notice that the `things` is not capitalised"oneOf:
- type: objectrequired:
- idproperties:
id:
type: integer
- type: objectrequired:
- idproperties:
id:
type: stringformat: uuid

This will produce:

// OneOf2things Notice that the `things` is not capitalisedtypeOneOf2thingsstruct {
union json.RawMessage
}
// Pet defines model for Pet.typePetstruct {
// Name The name of the pet.Namestring`json:"name"`// Uuid The pet uuid.Uuidstring`json:"uuid"`
}
// The interface specification for the client above.typeClientInterfaceinterface {
// GetHttpPet requestGetHttpPet(ctx context.Context, petIdstring, reqEditors...RequestEditorFn) (*http.Response, error)
}

Example, using ToCamelCaseWithInitialisms

By default, oapi-codegen will perform camel-case conversion, so for a spec such as:

openapi: "3.0.0"info:
version: 1.0.0title: Example code for the `name-normalizer` output optionpaths:
/api/pets/{petId}:
get:
summary: Get pet given identifier.operationId: getHttpPetparameters:
- name: petIdin: pathrequired: trueschema:
type: stringresponses:
'200':
description: valid petcontent:
application/json:
schema:
$ref: '#/components/schemas/Pet'components:
schemas:
Pet:
type: objectrequired:
- uuid
- nameproperties:
uuid:
type: stringdescription: The pet uuid.name:
type: stringdescription: The name of the pet.Error:
required:
- code
- messageproperties:
code:
type: integerformat: int32description: Error codemessage:
type: stringdescription: Error messageOneOf2things:
description: "Notice that the `things` is not capitalised"oneOf:
- type: objectrequired:
- idproperties:
id:
type: integer
- type: objectrequired:
- idproperties:
id:
type: stringformat: uuid

This will produce:

// OneOf2things Notice that the `things` is not capitalisedtypeOneOf2thingsstruct {
union json.RawMessage
}
// Pet defines model for Pet.typePetstruct {
// Name The name of the pet.Namestring`json:"name"`// UUID The pet uuid.UUIDstring`json:"uuid"`
}
// The interface specification for the client above.typeClientInterfaceinterface {
// GetHTTPPet requestGetHTTPPet(ctx context.Context, petIDstring, reqEditors...RequestEditorFn) (*http.Response, error)
}

For more details of what the resulting code looks like, check out the test cases.

Examples

The examples directory contains some additional cases which are useful examples for how to use oapi-codegen, including how you'd take the Petstore API and implement it with oapi-codegen.

You could also find some cases of how the project can be used by checking out our internal test cases 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:

Got one to add? Please raise a PR!

Frequently Asked Questions (FAQs)

How does `oapi-codegen` handle `anyOf`, `allOf` and `oneOf`?

oapi-codegen supports anyOf, allOf and oneOf for generated code.

For instance, through the following OpenAPI spec:

openapi: "3.0.0"info:
version: 1.0.0title: Using complex schemasdescription: An example of `anyOf`, `allOf` and `oneOf`components:
schemas:
# base typesClient:
type: objectrequired:
- nameproperties:
name:
type: stringIdentity:
type: objectrequired:
- issuerproperties:
issuer:
type: string# allOf performs a union of all types definedClientWithId:
allOf:
- $ref: '#/components/schemas/Client'
- properties:
id:
type: integerrequired:
- id# allOf performs a union of all types defined, but if there's a duplicate field defined, it'll be overwritten by the last schema# https://github.com/deepmap/oapi-codegen/issues/1569IdentityWithDuplicateField:
allOf:
# `issuer` will be ignored
- $ref: '#/components/schemas/Identity'# `issuer` will be ignored
- properties:
issuer:
type: integer# `issuer` will take precedence
- properties:
issuer:
type: objectproperties:
name:
type: stringrequired:
- 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 retrieveClientAndMaybeIdentity:
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 retrieveClientOrIdentity:
oneOf:
- $ref: '#/components/schemas/Client'
- $ref: '#/components/schemas/Identity'

This results in the following types:

Base types

// Client defines model for Client.typeClientstruct {
Namestring`json:"name"`
}
// Identity defines model for Identity.typeIdentitystruct {
Issuerstring`json:"issuer"`
}

allOf

// ClientWithId defines model for ClientWithId.typeClientWithIdstruct {
Idint`json:"id"`Namestring`json:"name"`
}
// IdentityWithDuplicateField defines model for IdentityWithDuplicateField.typeIdentityWithDuplicateFieldstruct {
Issuerstruct {
Namestring`json:"name"`
} `json:"issuer"`
}

anyOf

import (
"encoding/json""github.com/oapi-codegen/runtime"
)
// ClientAndMaybeIdentity defines model for ClientAndMaybeIdentity.typeClientAndMaybeIdentitystruct {
union json.RawMessage
}
// AsClient returns the union data inside the ClientAndMaybeIdentity as a Clientfunc (tClientAndMaybeIdentity) AsClient() (Client, error) {
varbodyClienterr:=json.Unmarshal(t.union, &body)
returnbody, err
}
// FromClient overwrites any union data inside the ClientAndMaybeIdentity as the provided Clientfunc (t*ClientAndMaybeIdentity) FromClient(vClient) error {
b, err:=json.Marshal(v)
t.union=breturnerr
}
// MergeClient performs a merge with any union data inside the ClientAndMaybeIdentity, using the provided Clientfunc (t*ClientAndMaybeIdentity) MergeClient(vClient) error {
b, err:=json.Marshal(v)
iferr!=nil {
returnerr
}
merged, err:=runtime.JSONMerge(t.union, b)
t.union=mergedreturnerr
}
// AsIdentity returns the union data inside the ClientAndMaybeIdentity as a Identityfunc (tClientAndMaybeIdentity) AsIdentity() (Identity, error) {
varbodyIdentityerr:=json.Unmarshal(t.union, &body)
returnbody, err
}
// FromIdentity overwrites any union data inside the ClientAndMaybeIdentity as the provided Identityfunc (t*ClientAndMaybeIdentity) FromIdentity(vIdentity) error {
b, err:=json.Marshal(v)
t.union=breturnerr
}
// MergeIdentity performs a merge with any union data inside the ClientAndMaybeIdentity, using the provided Identityfunc (t*ClientAndMaybeIdentity) MergeIdentity(vIdentity) error {
b, err:=json.Marshal(v)
iferr!=nil {
returnerr
}
merged, err:=runtime.JSONMerge(t.union, b)
t.union=mergedreturnerr
}
func (tClientAndMaybeIdentity) MarshalJSON() ([]byte, error) {
b, err:=t.union.MarshalJSON()
returnb, err
}
func (t*ClientAndMaybeIdentity) UnmarshalJSON(b []byte) error {
err:=t.union.UnmarshalJSON(b)
returnerr
}

oneOf

// AsClient returns the union data inside the ClientOrIdentity as a Clientfunc (tClientOrIdentity) AsClient() (Client, error) {
varbodyClienterr:=json.Unmarshal(t.union, &body)
returnbody, err
}
// FromClient overwrites any union data inside the ClientOrIdentity as the provided Clientfunc (t*ClientOrIdentity) FromClient(vClient) error {
b, err:=json.Marshal(v)
t.union=breturnerr
}
// MergeClient performs a merge with any union data inside the ClientOrIdentity, using the provided Clientfunc (t*ClientOrIdentity) MergeClient(vClient) error {
b, err:=json.Marshal(v)
iferr!=nil {
returnerr
}
merged, err:=runtime.JSONMerge(t.union, b)
t.union=mergedreturnerr
}
// AsIdentity returns the union data inside the ClientOrIdentity as a Identityfunc (tClientOrIdentity) AsIdentity() (Identity, error) {
varbodyIdentityerr:=json.Unmarshal(t.union, &body)
returnbody, err
}
// FromIdentity overwrites any union data inside the ClientOrIdentity as the provided Identityfunc (t*ClientOrIdentity) FromIdentity(vIdentity) error {
b, err:=json.Marshal(v)
t.union=breturnerr
}
// MergeIdentity performs a merge with any union data inside the ClientOrIdentity, using the provided Identityfunc (t*ClientOrIdentity) MergeIdentity(vIdentity) error {
b, err:=json.Marshal(v)
iferr!=nil {
returnerr
}
merged, err:=runtime.JSONMerge(t.union, b)
t.union=mergedreturnerr
}
func (tClientOrIdentity) MarshalJSON() ([]byte, error) {
b, err:=t.union.MarshalJSON()
returnb, err
}
func (t*ClientOrIdentity) UnmarshalJSON(b []byte) error {
err:=t.union.UnmarshalJSON(b)
returnerr
}

For more info, check out the example code.

How can I ignore parts of the spec I don't care about?

By default, oapi-codegen will generate everything from the specification.

If you'd like to reduce what's generated, you can use one of a few options in the configuration file to tune the generation of the resulting output:

# yaml-language-server: $schema=https://raw.githubusercontent.com/deepmap/oapi-codegen/HEAD/configuration-schema.jsonoutput-options:
include-tags: []exclude-tags: []include-operation-ids: []exclude-operation-ids: []exclude-schemas: []

Check the docs for more details of usage.

Should I commit the generated code?

We recommend doing so, yes, for the following reasons:

It means it's easier to view the impact of a change - be it due to an upgrade of oapi-codegen, or a change to your spec - and has helped catch (possibly) breaking changes in the past more easily
It then allows your codebase to be consumed as a library, as all the files are committed

This means you'll need to have your CI/CD pipeline validate that generated files are all up-to-date, but that's a fairly straightforward piece of work.

Should I lint the generated code?

We really ask that you don't. Although it intends to be idiomatic Go code, it's not expected to pass all the various linting rules that your project may apply.

Note

We will, on occasion, improve the generated code to fix some linting warnings, such as those from go vet, but this should not be an expected change.

I've just updated my version of `kin-openapi`, and now I can't build my code 😠

The kin-openapi project - which we 💜 for providing a great library and set of tooling for interacting with OpenAPI - is a pre-v1 release, which means that they're within their rights to push breaking changes.

This may lead to breakage in your consuming code, and if so, sorry that's happened!

We'll be aware of the issue, and will work to update both the core oapi-codegen and the middlewares accordingly.

Name		Name	Last commit message	Last commit date
Latest commit History 753 Commits
.github		.github
cmd/oapi-codegen		cmd/oapi-codegen
examples		examples
internal/test		internal/test
pkg		pkg
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
configuration-schema.json		configuration-schema.json
go.mod		go.mod
go.sum		go.sum
renovate.json		renovate.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

oapi-codegen

Install

Pinning to commits

Usage

Backwards compatibility

Features

What does it look like?

Key design decisions

Generating server-side boilerplate

Supported Servers

Go 1.22+ net/http

Chi

gorilla/mux

Echo server

Fiber server

Gin server

Iris server

Strict server

Generating API clients

Generating API models

Splitting large OpenAPI specs across multiple packages (aka "Import Mapping" or "external references")

Generating Nullable types

OpenAPI extensions

Request/response validation middleware

Implementing security

On the server

On the client

Custom code generation

Local paths

HTTPS paths

Inline template

Using the Go package

Additional Properties (additionalProperties)

Implicit additionalProperties: true / no additionalProperties set

Explicit additionalProperties: true

additionalProperties as integers

additionalProperties with an object

Changing the names of generated types

Examples

Blog posts

Frequently Asked Questions (FAQs)

How does oapi-codegen handle anyOf, allOf and oneOf?

How can I ignore parts of the spec I don't care about?

Should I commit the generated code?

Should I lint the generated code?

I've just updated my version of kin-openapi, and now I can't build my code 😠

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`oapi-codegen`

Go 1.22+ `net/http`

Additional Properties (`additionalProperties`)

Implicit `additionalProperties: true` / no `additionalProperties` set

Explicit `additionalProperties: true`

`additionalProperties` as `integer`s

`additionalProperties` with an object

How does `oapi-codegen` handle `anyOf`, `allOf` and `oneOf`?

I've just updated my version of `kin-openapi`, and now I can't build my code 😠