Action Required: The repository for this project has changed

Important

oapi-codegen moved to its new home with the version tagv2.3.0.

# for the binary installgo install github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen@v2.2.0

# for the binary installgo install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest

Install

For Go 1.24+

$ go get -tool github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest# this will then modify your `go.mod`

//go:generate go tool oapi-codegen -config cfg.yaml ../../api.yaml

Prior to Go 1.24

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

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

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

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

Pinning to commits

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

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

Usage

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

Backwards compatibility

Features

What does it look like?

// 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) {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)}// 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}

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)}

// 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))}}

// 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}

Key design decisions

Generating server-side boilerplate

Supported Servers

Go 1.22+net/http

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

// 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,mServeMux) 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}

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)}

import ("log""net/http""github.com/oapi-codegen/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 includevalidation of incoming requests.

Note

If you feel like you've done everything right, but are still receiving404 page not found errors, make sure that you've got thego directive in yourgo.mod updated to:

go1.22

Chi

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

// 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}

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)}

import ("log""net/http""github.com/oapi-codegen/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 includevalidation of incoming requests.

gorilla/mux

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

// 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}

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)}

import ("log""net/http""github.com/oapi-codegen/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 includevalidation of incoming requests.

Echo server

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

// 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)}

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)}

import ("log""github.com/oapi-codegen/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 includevalidation of incoming requests.

Fiber server

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

// 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)}

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)}

import ("log""github.com/oapi-codegen/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 includevalidation of incoming requests.

Gin server

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

// 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)}

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)}

import ("log""net/http""github.com/oapi-codegen/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 includevalidation of incoming requests.

Iris server

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

// 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()}

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)}

import ("log""github.com/oapi-codegen/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 includevalidation of incoming requests.

Strict server

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

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/oapi-codegen/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 includevalidation of incoming requests.

Generating API clients

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

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

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

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}// ...

package client_testimport ("context""fmt""log""net/http""github.com/oapi-codegen/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)}}

With Server URLs

servers:-url:https://development.gigantic-server.com/v1description:Development server-url:https://{username}.gigantic-server.com:{port}/{basePath}description:The production API servervariables:username:# note! no enum here means it is an open valuedefault:demodescription:this value is assigned by the service provider, in this example `gigantic-server.com`port:enum:        -'8443'        -'443'default:'8443'basePath:# open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`default:v2

# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/HEAD/configuration-schema.jsonpackage:serverurlsoutput:gen.gogenerate:# NOTE that this uses default settings - if you want to use initialisms to generate i.e. `ServerURLDevelopmentServer`, you should look up the `output-options.name-normalizer` configurationserver-urls:true

// (the below does not include comments that are generated)constServerUrlDevelopmentServer="https://development.gigantic-server.com/v1"typeServerUrlTheProductionAPIServerBasePathVariablestringconstServerUrlTheProductionAPIServerBasePathVariableDefault="v2"typeServerUrlTheProductionAPIServerPortVariablestringconstServerUrlTheProductionAPIServerPortVariable8443ServerUrlTheProductionAPIServerPortVariable="8443"constServerUrlTheProductionAPIServerPortVariable443ServerUrlTheProductionAPIServerPortVariable="443"constServerUrlTheProductionAPIServerPortVariableDefaultServerUrlTheProductionAPIServerPortVariable=ServerUrlTheProductionAPIServerPortVariable8443typeServerUrlTheProductionAPIServerUsernameVariablestringconstServerUrlTheProductionAPIServerUsernameVariableDefault="demo"funcServerUrlTheProductionAPIServer(basePathServerUrlTheProductionAPIServerBasePathVariable,portServerUrlTheProductionAPIServerPortVariable,usernameServerUrlTheProductionAPIServerUsernameVariable) (string,error) {// ...}

Duplicate types generated for clients's response object types

openapi:"3.0.0"info:version:1.0.0title:"Show that generated client boilerplate can clash if schemas are well named i.e. `*Request` and `*Response`"paths:/client:put:operationId:updateClientrequestBodies:application/json:schema:$ref:'#/components/schemas/UpdateClientRequest'responses:400:content:application/json:schema:$ref:'#/components/schemas/UpdateClientResponse'components:schemas:UpdateClientRequest:type:objectproperties:code:type:stringrequired:      -codeUpdateClientResponse:type:objectrequired:        -nameproperties:name:type:string

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

# github.com/oapi-codegen/oapi-codegen/v2/examples/clienttypenameclash./client.gen.go:184:6: UpdateClientResponse redeclared in this block        ./client.gen.go:17:6: other declaration of UpdateClientResponse./client.gen.go:192:7: r.HTTPResponse undefined (type UpdateClientResponse has no field or method HTTPResponse)./client.gen.go:193:12: r.HTTPResponse undefined (type UpdateClientResponse has no field or method HTTPResponse)./client.gen.go:200:7: r.HTTPResponse undefined (type UpdateClientResponse has no field or method HTTPResponse)./client.gen.go:201:12: r.HTTPResponse undefined (type UpdateClientResponse has no field or method HTTPResponse)./client.gen.go:224:3: unknown field Body in struct literal of type UpdateClientResponse./client.gen.go:225:3: unknown field HTTPResponse in struct literal of type UpdateClientResponse./client.gen.go:234:12: response.JSON400 undefined (type *UpdateClientResponse has no field or method JSON400)

 # yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json package: client output: client.gen.go generate:   models: true   client: true+output-options:+  response-type-suffix: Resp

-type UpdateClientResponse struct {+type UpdateClientResp struct {        Body         []byte        HTTPResponse *http.Response        JSON400      *UpdateClientResponse }

Generating API models

Tip

Try to define as much as possible within the#/components/schemas object, asoapi-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.

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/oapi-codegen/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

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

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

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

# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/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

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

responses:200:description:Successcontent:application/json:schema:$ref:'#/components/schemas/User'

# 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:'../common/api.yaml#/components/schemas/User'

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

Using a single package with multiple OpenAPI specs

Tip

Sinceoapi-codegen v2.4.0, it is now possible to split large OpenAPI specifications into the same Go package, using the "self" mapping (denoted by a-) when using Import Mapping.

This is an improvement on the previous model, which would require splitting files across multiple packages.

Note

You still need to have multiplego generates, and any other configuration files.

$ go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen -config cfg-api.yaml ../admin/api.yaml$ go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen -config cfg-user.yaml ../common/api.yaml

# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/HEAD/configuration-schema.jsonpackage:samepackageoutput:server.gen.gogenerate:models:truechi-server:truestrict-server:trueoutput-options:# to make sure that all types are generatedskip-prune:trueimport-mapping:user.yaml:"-"

# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/HEAD/configuration-schema.jsonpackage:samepackageoutput:user.gen.gogenerate:models:trueoutput-options:# to make sure that all types are generatedskip-prune:true

Using multiple packages, with one OpenAPI spec per package

├── admin│   ├── cfg.yaml│   └── generate.go└── common    ├── cfg.yaml    └── generate.go

# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/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`

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

# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/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/oapi-codegen/oapi-codegen/v2/examples/import-mapping/common

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

Modifying the input OpenAPI Specification (with OpenAPI Overlay)

Caution

Beware! Here (may) be dragons.

The Overlay specification requires the use of JSON Path, which some users may find difficult to write and/or maintain.

We still heavily recommend using Overlay functionality, but would like users to be aware of this.

There is aproposed modification to the specification which would relax the need for JSON Path as the targeting mechanism.

openapi:"3.0.0"info:version:1.0.0title:"Example to indicate how to use the OpenAPI Overlay specification (https://github.com/OAI/Overlay-Specification)"paths:/ping:get:responses:'200':description:pet responsecontent:application/json:schema:$ref:'#/components/schemas/Pong'delete:x-internal:trueresponses:'202':content:{}

overlay:1.0.0info:title:Overlayversion:0.0.0actions:-target:"$"description:Perform a structural overlay, which can be more readable, as it's clear what the shape of the document isupdate:info:x-overlay-applied:structured-overlaypaths:/ping:get:responses:'200':description:Perform a ping request-target:$.paths.*[?(@.x-internal)]description:Remove internal endpoints (noted by x-internal)remove:true-target:$.paths.*.*[?(@.x-internal)]description:Remove internal endpoints (noted by x-internal)remove:true

# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/HEAD/configuration-schema.jsonpackage:apioutput:ping.gen.gogenerate:models:truegorilla-server:trueembedded-spec:trueoutput-options:overlay:path:overlay.yaml

Generating Nullable types

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

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

output-options:nullable-type:true

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

OpenAPI extensions

x-go-type /x-go-type-import - override the generated type definition (and optionally, add an import from another package)

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

// Client defines model for Client.typeClientstruct {Id*float32`json:"id,omitempty"`Namestring`json:"name"`}// ClientWithExtension defines model for ClientWithExtension.typeClientWithExtensionstruct {Id*int64`json:"id,omitempty"`Name googleuuid.UUID`json:"name"`}

x-go-type-skip-optional-pointer - do not add a pointer type for optional fields in structs

Tip

If you prefer this behaviour, and prefer to not have to annotate your whole OpenAPI spec for this behaviour, you can useoutput-options.prefer-skip-optional-pointer=true to default this behaviour for all fields.

It is then possible to override this on a per-type/per-field basis where necessary.

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

// 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"`}

x-go-name - override the generated name of a field or a type

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

// Client defines model for Client.typeClientstruct {Id*float32`json:"id,omitempty"`Namestring`json:"name"`}// ClientRenamedByExtension defines model for ClientWithExtension.typeClientRenamedByExtensionstruct {AccountIdentifier*float32`json:"id,omitempty"`Namestring`json:"name"`}

x-go-type-name - Override the generated name of a type

Note

Notice that this is subtly different to thex-go-name, which also applies tofields withinstructs.

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

// Client defines model for Client.typeClientstruct {Id*float32`json:"id,omitempty"`Namestring`json:"name"`}// ClientWithExtension defines model for ClientWithExtension.typeClientWithExtension=ClientRenamedByExtension// ClientRenamedByExtension defines model for .typeClientRenamedByExtensionstruct {Id*float32`json:"id,omitempty"`Namestring`json:"name"`}

x-omitempty - force the presence of the JSON tagomitempty on a field

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

// Client defines model for Client.typeClientstruct {Id*float32`json:"id,omitempty"`Namestring`json:"name"`}// ClientWithExtension defines model for ClientWithExtension.typeClientWithExtensionstruct {Id*float32`json:"id,omitempty"`Namestring`json:"name,omitempty"`}

x-omitzero - force the presence of the JSON tagomitzero on a field

Note

omitzero was added in Go 1.24. If you're not using Go 1.24 in your project, this won't work.

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:stringid:type:numberx-omitzero:true

// Client defines model for Client.typeClientstruct {Id*float32`json:"id,omitempty"`Namestring`json:"name"`}// ClientWithExtension defines model for ClientWithExtension.typeClientWithExtensionstruct {Id*float32`json:"id,omitempty,omitzero"`Namestring`json:"name"`}

x-go-json-ignore - when (un)marshaling JSON, ignore field(s)

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

// Client defines model for Client.typeClientstruct {ComplexField*struct {AccountName*string`json:"accountName,omitempty"`Name*string`json:"name,omitempty"`}`json:"complexField,omitempty"`Namestring`json:"name"`}// ClientWithExtension defines model for ClientWithExtension.typeClientWithExtensionstruct {ComplexField*struct {AccountName*string`json:"accountName,omitempty"`Name*string`json:"name,omitempty"`}`json:"-"`Namestring`json:"name"`}

x-oapi-codegen-extra-tags - generate arbitrary struct tags to fields

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

// 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"`}

x-enum-varnames /x-enumNames - override generated variable names for enum constants

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

// Defines values for ClientType.const (ACTClientType="ACT"EXPClientType="EXP")// Defines values for ClientTypeWithNamesExtension.const (ClientTypeWithNamesExtensionActiveClientTypeWithNamesExtension="ACT"ClientTypeWithNamesExtensionExpiredClientTypeWithNamesExtension="EXP")// Defines values for ClientTypeWithVarNamesExtension.const (ClientTypeWithVarNamesExtensionActiveClientTypeWithVarNamesExtension="ACT"ClientTypeWithVarNamesExtensionExpiredClientTypeWithVarNamesExtension="EXP")// ClientType defines model for ClientType.typeClientTypestring// ClientTypeWithNamesExtension defines model for ClientTypeWithNamesExtension.typeClientTypeWithNamesExtensionstring// ClientTypeWithVarNamesExtension defines model for ClientTypeWithVarNamesExtension.typeClientTypeWithVarNamesExtensionstring

x-deprecated-reason - add a GoDoc deprecation warning to a type

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

// Client defines model for Client.typeClientstruct {Id*float32`json:"id,omitempty"`Namestring`json:"name"`}// ClientWithExtension defines model for ClientWithExtension.typeClientWithExtensionstruct {Id*float32`json:"id,omitempty"`// Deprecated: Don't use because reasonsNamestring`json:"name"`}

x-order - explicitly order struct fields

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

// Client defines model for Client.typeClientstruct {AName*string`json:"a_name,omitempty"`Id*float32`json:"id,omitempty"`}// ClientWithExtension defines model for ClientWithExtension.typeClientWithExtensionstruct {Id*float32`json:"id,omitempty"`AName*string`json:"a_name,omitempty"`}

x-oapi-codegen-only-honour-go-name - only honour thex-go-name when generating field names

Warning

Using this option may lead to cases whereoapi-codegen's rewriting of field names to prevent clashes with other types, or to prevent including characters that may not be valid Go field names.

openapi:"3.0.0"info:version:1.0.0title:x-oapi-codegen-only-honour-go-namecomponents:schemas:TypeWithUnexportedField:description:A struct will be output where one of the fields is not exportedproperties:name:type:stringid:type:string# NOTE that there is an explicit usage of a lowercase characterx-go-name:accountIdentifierx-oapi-codegen-extra-tags:json:"-"x-oapi-codegen-only-honour-go-name:true

// TypeWithUnexportedField A struct will be output where one of the fields is not exportedtypeTypeWithUnexportedFieldstruct {accountIdentifier*string`json:"-"`Name*string`json:"name,omitempty"`}

Request/response validation middleware

Note

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

Note

We're alsoexploring the use oflibopenapi-validator for request/response validation middleware

Implementing security

On the server

Note

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

To perform authentication, you will need to use thevalidation middleware.

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

On the client

import ("context""fmt""log""github.com/oapi-codegen/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)}

Custom code generation

Note

Filenames given to theuser-templates configuration mustexactly match the filename thatoapi-codegen is looking for

Local paths

# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/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

Warning

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

HTTPS paths

Warning

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

Seethis 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

# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/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/oapi-codegen/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/oapi-codegen/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/oapi-codegen/oapi-codegen/master/pkg/codegen/templates/client-with-responses.tmpl

Warning

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

Inline template

# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/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

Additional Properties (additionalProperties)

Note

In the futurethis will be possible to disable this functionality, and honour the implicitadditionalProperties: true

ImplicitadditionalProperties: true / noadditionalProperties set

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

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

ExplicitadditionalProperties: true

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

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

additionalProperties asintegers

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

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

additionalProperties with an object

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

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

Globally skipping the "optional pointer"

# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/HEAD/configuration-schema.jsonpackage:preferskipoptionalpointerwithomitzerooutput:gen.gogenerate:# ...output-options:# ...prefer-skip-optional-pointer:trueprefer-skip-optional-pointer-with-omitzero:true

openapi:"3.0.0"info:version:1.0.0title:prefer-skip-optional-pointer-with-omitzerocomponents:schemas:ClientWithExtension:type:objectrequired:        -nameproperties:name:description:This field is required, so will never have an optional pointer, nor `omitzero`.type:stringid:description:This field is optional, but the `prefer-skip-optional-pointer` Output Option ensures that this should not have an optional pointer. However, it will receive `omitzero`.type:numberpointer_id:type:numberdescription:This field should have an optional pointer, as the field-level definition of `x-go-type-skip-optional-pointer` overrides the `prefer-skip-optional-pointer` Output Option. This will also not receive an `omitzero`.# NOTE that this overrides the global preferencex-go-type-skip-optional-pointer:falseno_omit:type:numberdescription:This field is optional, but the `prefer-skip-optional-pointer` Output Option ensures that this should not have an optional pointer. This will not receive `omitzero`, as the field-level definition of `x-omitzero` overrides the `prefer-skip-optional-pointer-with-omitzero` Output Option.# NOTE that this overrides the global preferencex-omitzero:false

// ...// ClientWithExtension defines model for ClientWithExtension.typeClientWithExtensionstruct {// Id This field is optional, but the `prefer-skip-optional-pointer` Output Option ensures that this should not have an optional pointer. However, it will receive `omitzero`.Idfloat32`json:"id,omitempty,omitzero"`// Name This field is required, so will never have an optional pointer, nor `omitzero`.Namestring`json:"name"`// NoOmit This field is optional, but the `prefer-skip-optional-pointer` Output Option ensures that this should not have an optional pointer. This will not receive `omitzero`, as the field-level definition of `x-omitzero` overrides the `prefer-skip-optional-pointer-with-omitzero` Output Option.NoOmitfloat32`json:"no_omit,omitempty"`// PointerId This field should have an optional pointer, as the field-level definition of `x-go-type-skip-optional-pointer` overrides the `prefer-skip-optional-pointer` Output Option. This will also not receive an `omitzero`.PointerId*float32`json:"pointer_id,omitempty"`}

Changing the names of generated types

Examples

Blog posts

Frequently Asked Questions (FAQs)

Doesoapi-codegen support OpenAPI 3.1?

How doesoapi-codegen handleanyOf,allOf andoneOf?

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/oapi-codegen/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'

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

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

Should I commit the generated code?

Should I lint the generated code?

Note

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

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

Contributors

Sponsors