📚 oapi-codegen - Awesome Go Library for Generators
This package contains a set of utilities for generating Go boilerplate code for services based on OpenAPI 3.0 API definitions.
Detailed Description of oapi-codegen
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.
Action Required: The repository for this project has changed
As announced in May 2024,
we have moved the project from the deepmap organization to our own organization, and you will need to update your
import paths to pull updates past this point. You need to do a recursive search/replace from
github.com/deepmap/oapi-codegen/v2 to github.com/oapi-codegen/oapi-codegen/v2.
[!IMPORTANT]
oapi-codegenmoved to its new home with the version tagv2.3.0.
If you are using v2.2.0 or below, please install like so:
# for the binary install
go install github.com/deepmap/oapi-codegen/v2/cmd/[email protected]
If you are using v2.3.0 or above, please install like so, using the new module import path:
# for the binary install
go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest
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 tools
package main
import (
_ "github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen"
)
Then, each invocation of oapi-codegen would be used like so:
//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen --config=config.yaml ../../api.yaml
Alternatively, you can install it as a binary with:
$ go install github.com/oapi-codegen/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
Note that you can also move your tools.go into its own sub-module to reduce the impact on your top-level go.mod.
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/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
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/oapi-codegen/oapi-codegen/v2 v2.1.0
+require github.com/oapi-codegen/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/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json
package: 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 code
type ServerInterface interface {
// ...
// Returns all pets
// (GET /pets)
FindPets(w http.ResponseWriter, r *http.Request, params FindPetsParams)
// ...
}
// FindPets operation middleware
func (siw *ServerInterfaceWrapper) FindPets(w http.ResponseWriter, r *http.Request) {
var err error
// Parameter object where we will unmarshal all parameters from the context
var params FindPetsParams
// ------------- Optional query parameter "tags" -------------
err = runtime.BindQueryParameter("form", true, false, "tags", r.URL.Query(), ¶ms.Tags)
if err != 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(), ¶ms.Limit)
if err != 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 := range siw.HandlerMiddlewares {
handler = middleware(handler)
}
handler.ServeHTTP(w, r)
}
// HandlerWithOptions creates http.Handler with additional options
func HandlerWithOptions(si ServerInterface, options StdHTTPServerOptions) http.Handler {
m := options.BaseRouter
if m == nil {
m = http.NewServeMux()
}
if options.ErrorHandlerFunc == nil {
options.ErrorHandlerFunc = func(w http.ResponseWriter, r *http.Request, err error) {
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)
return m
}
Then, in your own code, you implement the underlying logic for the FindPets implementation:
type PetStore struct {
Pets map[int64]Pet
NextId int64
Lock sync.Mutex
}
// Make sure we conform to ServerInterface
var _ ServerInterface = (*PetStore)(nil)
func NewPetStore() *PetStore {
return &PetStore{
Pets: make(map[int64]Pet),
NextId: 1000,
}
}
// FindPets implements all the handlers in the ServerInterface
func (p *PetStore) FindPets(w http.ResponseWriter, r *http.Request, params FindPetsParams) {
p.Lock.Lock()
defer p.Lock.Unlock()
var result []Pet
for _, pet := range p.Pets {
if params.Tags != nil {
// If we have tags, filter pets by tag
for _, t := range *params.Tags {
if pet.Tag != nil && (*pet.Tag == t) {
result = append(result, pet)
}
}
} else {
// Add all pets if we're not filtering
result = append(result, pet)
}
if params.Limit != nil {
l := int(*params.Limit)
if len(result) >= l {
// We're at the limit
break
}
}
}
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.
type StrictServerInterface interface {
// ...
// Returns all pets
// (GET /pets)
FindPets(ctx context.Context, request FindPetsRequestObject) (FindPetsResponseObject, error)
// ...
}
func NewStrictHandlerWithOptions(ssi StrictServerInterface, middlewares []StrictMiddlewareFunc, options StrictHTTPServerOptions) ServerInterface {
return &strictHandler{ssi: ssi, middlewares: middlewares, options: options}
}
// FindPets operation middleware
func (sh *strictHandler) FindPets(w http.ResponseWriter, r *http.Request, params FindPetsParams) {
var request FindPetsRequestObject
request.Params = params
handler := func(ctx context.Context, w http.ResponseWriter, r *http.Request, request interface{}) (interface{}, error) {
return sh.ssi.FindPets(ctx, request.(FindPetsRequestObject))
}
for _, middleware := range sh.middlewares {
handler = middleware(handler, "FindPets")
}
response, err := handler(r.Context(), w, r, request)
if err != nil {
sh.options.ResponseErrorHandlerFunc(w, r, err)
} else if validResponse, ok := response.(FindPetsResponseObject); ok {
if err := validResponse.VisitFindPetsResponse(w); err != nil {
sh.options.ResponseErrorHandlerFunc(w, r, err)
}
} else if response != 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 StrictServerInterface
var _ StrictServerInterface = (*PetStore)(nil)
func NewPetStore() *PetStore {
return &PetStore{
Pets: make(map[int64]Pet),
NextId: 1000,
}
}
// FindPets implements all the handlers in the ServerInterface
func (p *PetStore) FindPets(ctx context.Context, request FindPetsRequestObject) (FindPetsResponseObject, error) {
p.Lock.Lock()
defer p.Lock.Unlock()
var result []Pet
for _, pet := range p.Pets {
if request.Params.Tags != nil {
// If we have tags, filter pets by tag
for _, t := range *request.Params.Tags {
if pet.Tag != nil && (*pet.Tag == t) {
result = append(result, pet)
}
}
} else {
// Add all pets if we're not filtering
result = append(result, pet)
}
if request.Params.Limit != nil {
l := int(*request.Params.Limit)
if len(result) >= l {
// We're at the limit
break
}
}
}
return FindPets200JSONResponse(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
additionalPropertiesare 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-server
|
For a Chi server, you will want a configuration file such as: To implement this, check out the Chi docs. | |
echo-server
|
For an Echo server, you will want a configuration file such as: To implement this, check out the Echo docs. | |
fiber-server
|
For a Fiber server, you will want a configuration file such as: To implement this, check out the Fiber docs. | |
gin-server
|
For a Gin server, you will want a configuration file such as: To implement this, check out the Gin docs. | |
gorilla-server
|
For a gorilla/mux server, you will want a configuration file such as: To implement this, check out the gorilla/mux docs. | |
iris-server
|
For a Iris server, you will want a configuration file such as: To implement this, check out the Iris docs. | |
std-http-server
|
To use purely To implement this, check out the Go 1.22+ |
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.0
title: Minimal ping API server
paths:
/ping:
get:
responses:
'200':
description: pet response
content:
application/json:
schema:
$ref: '#/components/schemas/Pong'
components:
schemas:
# base types
Pong:
type: object
required:
- ping
properties:
ping:
type: string
example: pong
This then generates code such as:
// Pong defines model for Pong.
type Pong struct {
Ping string `json:"ping"`
}
// ServerInterface represents all server handlers.
type ServerInterface interface {
// (GET /ping)
GetPing(w http.ResponseWriter, r *http.Request)
}
func HandlerFromMux(si ServerInterface, m ServeMux) http.Handler {
return HandlerWithOptions(si, StdHTTPServerOptions{
BaseRouter: m,
})
}
// HandlerWithOptions creates http.Handler with additional options
func HandlerWithOptions(si ServerInterface, options StdHTTPServerOptions) http.Handler {
m := options.BaseRouter
// ... omitted for brevity
m.HandleFunc("GET "+options.BaseURL+"/ping", wrapper.GetPing)
return m
}
To implement this HTTP server, we need to write the following code in our api/impl.go:
import (
"encoding/json"
"net/http"
)
// optional code omitted
type Server struct{}
func NewServer() Server {
return Server{}
}
// (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/oapi-codegen/oapi-codegen/v2/examples/minimal-server/stdhttp/api"
)
func main() {
// create a type that satisfies the `api.ServerInterface`, which contains an implementation of every operation from the generated code
server := api.NewServer()
r := http.NewServeMux()
// get an `http.Handler` that we can use
h := 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 founderrors, make sure that you've got thegodirective in yourgo.modupdated to:
go 1.22
Chi
For instance, let's take this straightforward specification:
openapi: "3.0.0"
info:
version: 1.0.0
title: Minimal ping API server
paths:
/ping:
get:
responses:
'200':
description: pet response
content:
application/json:
schema:
$ref: '#/components/schemas/Pong'
components:
schemas:
# base types
Pong:
type: object
required:
- ping
properties:
ping:
type: string
example: pong
This then generates code such as:
// Pong defines model for Pong.
type Pong struct {
Ping string `json:"ping"`
}
// ServerInterface represents all server handlers.
type ServerInterface interface {
// (GET /ping)
GetPing(w http.ResponseWriter, r *http.Request)
}
// HandlerFromMux creates http.Handler with routing matching OpenAPI spec based on the provided mux.
func HandlerFromMux(si ServerInterface, r *mux.Router) http.Handler {
return HandlerWithOptions(si, ChiServerOptions{
BaseRouter: r,
})
}
// HandlerWithOptions creates http.Handler with additional options
func HandlerWithOptions(si ServerInterface, options ChiServerOptions) http.Handler {
r := options.BaseRouter
// ...
r.Group(func(r chi.Router) {
r.Get(options.BaseURL+"/ping", wrapper.GetPing)
})
return r
}
To implement this HTTP server, we need to write the following code in our api/impl.go:
import (
"encoding/json"
"net/http"
)
// optional code omitted
type Server struct{}
func NewServer() Server {
return Server{}
}
// (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/oapi-codegen/oapi-codegen/v2/examples/minimal-server/chi/api"
"github.com/go-chi/chi/v5"
)
func main() {
// create a type that satisfies the `api.ServerInterface`, which contains an implementation of every operation from the generated code
server := api.NewServer()
r := chi.NewMux()
// get an `http.Handler` that we can use
h := 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.0
title: Minimal ping API server
paths:
/ping:
get:
responses:
'200':
description: pet response
content:
application/json:
schema:
$ref: '#/components/schemas/Pong'
components:
schemas:
# base types
Pong:
type: object
required:
- ping
properties:
ping:
type: string
example: pong
This then generates code such as:
// Pong defines model for Pong.
type Pong struct {
Ping string `json:"ping"`
}
// ServerInterface represents all server handlers.
type ServerInterface interface {
// (GET /ping)
GetPing(w http.ResponseWriter, r *http.Request)
}
// HandlerFromMux creates http.Handler with routing matching OpenAPI spec based on the provided mux.
func HandlerFromMux(si ServerInterface, r *mux.Router) http.Handler {
return HandlerWithOptions(si, GorillaServerOptions{
BaseRouter: r,
})
}
// HandlerWithOptions creates http.Handler with additional options
func HandlerWithOptions(si ServerInterface, options GorillaServerOptions) http.Handler {
r := options.BaseRouter
// ...
r.HandleFunc(options.BaseURL+"/ping", wrapper.GetPing).Methods("GET")
return r
}
To implement this HTTP server, we need to write the following code in our api/impl.go:
import (
"encoding/json"
"net/http"
)
// optional code omitted
type Server struct{}
func NewServer() Server {
return Server{}
}
// (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/oapi-codegen/oapi-codegen/v2/examples/minimal-server/gorillamux/api"
"github.com/gorilla/mux"
)
func main() {
// create a type that satisfies the `api.ServerInterface`, which contains an implementation of every operation from the generated code
server := api.NewServer()
r := mux.NewRouter()
// get an `http.Handler` that we can use
h := 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.0
title: Minimal ping API server
paths:
/ping:
get:
responses:
'200':
description: pet response
content:
application/json:
schema:
$ref: '#/components/schemas/Pong'
components:
schemas:
# base types
Pong:
type: object
required:
- ping
properties:
ping:
type: string
example: pong
This then generates code such as:
// Pong defines model for Pong.
type Pong struct {
Ping string `json:"ping"`
}
// ServerInterface represents all server handlers.
type ServerInterface interface {
// (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 registration
type EchoRouter interface {
// ...
GET(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) *echo.Route
// ...
}
// RegisterHandlers adds each server route to the EchoRouter.
func RegisterHandlers(router EchoRouter, si ServerInterface) {
RegisterHandlersWithBaseURL(router, si, "")
}
// Registers handlers, and prepends BaseURL to the paths, so that the paths
// can be served under a prefix.
func RegisterHandlersWithBaseURL(router EchoRouter, si ServerInterface, baseURL string) {
// ...
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 omitted
type Server struct{}
func NewServer() Server {
return Server{}
}
// (GET /ping)
func (Server) GetPing(ctx echo.Context) error {
resp := Pong{
Ping: "pong",
}
return 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"
"github.com/oapi-codegen/oapi-codegen/v2/examples/minimal-server/echo/api"
"github.com/labstack/echo/v4"
)
func main() {
// create a type that satisfies the `api.ServerInterface`, which contains an implementation of every operation from the generated code
server := 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.0
title: Minimal ping API server
paths:
/ping:
get:
responses:
'200':
description: pet response
content:
application/json:
schema:
$ref: '#/components/schemas/Pong'
components:
schemas:
# base types
Pong:
type: object
required:
- ping
properties:
ping:
type: string
example: pong
This then generates code such as:
// Pong defines model for Pong.
type Pong struct {
Ping string `json:"ping"`
}
// ServerInterface represents all server handlers.
type ServerInterface interface {
// (GET /ping)
GetPing(c *fiber.Ctx) error
}
// RegisterHandlers creates http.Handler with routing matching OpenAPI spec.
func RegisterHandlers(router fiber.Router, si ServerInterface) {
RegisterHandlersWithOptions(router, si, FiberServerOptions{})
}
// RegisterHandlersWithOptions creates http.Handler with additional options
func RegisterHandlersWithOptions(router fiber.Router, si ServerInterface, options FiberServerOptions) {
// ...
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 check
var _ ServerInterface = (*Server)(nil)
type Server struct{}
func NewServer() Server {
return Server{}
}
// (GET /ping)
func (Server) GetPing(ctx *fiber.Ctx) error {
resp := Pong{
Ping: "pong",
}
return ctx.
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/oapi-codegen/oapi-codegen/v2/examples/minimal-server/fiber/api"
"github.com/gofiber/fiber/v2"
)
func main() {
// create a type that satisfies the `api.ServerInterface`, which contains an implementation of every operation from the generated code
server := 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.0
title: Minimal ping API server
paths:
/ping:
get:
responses:
'200':
description: pet response
content:
application/json:
schema:
$ref: '#/components/schemas/Pong'
components:
schemas:
# base types
Pong:
type: object
required:
- ping
properties:
ping:
type: string
example: pong
This then generates code such as:
// Pong defines model for Pong.
type Pong struct {
Ping string `json:"ping"`
}
// ServerInterface represents all server handlers.
type ServerInterface interface {
// (GET /ping)
GetPing(c *gin.Context)
}
// RegisterHandlers creates http.Handler with routing matching OpenAPI spec.
func RegisterHandlers(router gin.IRouter, si ServerInterface) {
RegisterHandlersWithOptions(router, si, GinServerOptions{})
}
// RegisterHandlersWithOptions creates http.Handler with additional options
func RegisterHandlersWithOptions(router gin.IRouter, si ServerInterface, options GinServerOptions) {
// ...
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 omitted
type Server struct{}
func NewServer() Server {
return Server{}
}
// (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/oapi-codegen/oapi-codegen/v2/examples/minimal-server/gin/api"
"github.com/gin-gonic/gin"
)
func main() {
// create a type that satisfies the `api.ServerInterface`, which contains an implementation of every operation from the generated code
server := 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.0
title: Minimal ping API server
paths:
/ping:
get:
responses:
'200':
description: pet response
content:
application/json:
schema:
$ref: '#/components/schemas/Pong'
components:
schemas:
# base types
Pong:
type: object
required:
- ping
properties:
ping:
type: string
example: pong
This then generates code such as:
// Pong defines model for Pong.
type Pong struct {
Ping string `json:"ping"`
}
// ServerInterface represents all server handlers.
type ServerInterface interface {
// (GET /ping)
GetPing(ctx iris.Context)
}
// RegisterHandlers creates http.Handler with routing matching OpenAPI spec.
func RegisterHandlers(router *iris.Application, si ServerInterface) {
RegisterHandlersWithOptions(router, si, IrisServerOptions{})
}
// RegisterHandlersWithOptions creates http.Handler with additional options
func RegisterHandlersWithOptions(router *iris.Application, si ServerInterface, options IrisServerOptions) {
// ...
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 omitted
type Server struct{}
func NewServer() Server {
return Server{}
}
// (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/oapi-codegen/oapi-codegen/v2/examples/minimal-server/iris/api"
"github.com/kataras/iris/v12"
)
func main() {
// create a type that satisfies the `api.ServerInterface`, which contains an implementation of every operation from the generated code
server := 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-dataandapplication/x-www-form-urlencodedrequests - returning an HTTP 500 Internal Server Error, when an
erroris returned from a function - automagic (un)marshalling of request/responses, and setting
content-typeand HTTP status codes on responses - binding request values to a struct, a
multipart.Readeror providing aio.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/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json
package: api
generate:
# NOTE another server must be added!
chi-server: true
strict-server: true
output: 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.0
title: Generate models
paths:
/client:
get:
operationId: getClient
responses:
200:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientType"
put:
operationId: updateClient
responses:
400:
content:
application/json:
schema:
type: object
properties:
code:
type: string
required:
- code
components:
schemas:
ClientType:
type: object
required:
- name
properties:
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: true
Unreferenced:
type: object
required:
- id
properties:
id:
type: integer
And a cfg.yaml:
# 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
And a generate.go:
package client
//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen -config cfg.yaml api.yaml
This would then generate:
package client
// ...
// ClientType defines model for ClientType.
type ClientType struct {
Name string `json:"name"`
}
// ...
// Client which conforms to the OpenAPI3 specification for this service.
type Client struct {
// The endpoint of the server conforming to this interface, with scheme,
// https://api.deepmap.com for example. 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.
Server string
// Doer for performing requests, typically a *http.Client with any
// customized settings, such as certificate chains.
Client HttpRequestDoer
// A list of callbacks for modifying requests which are generated before sending over
// the network.
RequestEditors []RequestEditorFn
}
// ...
// The interface specification for the client above.
type ClientInterface interface {
// GetClient request
GetClient(ctx context.Context, reqEditors ...RequestEditorFn) (*http.Response, error)
// UpdateClient request
UpdateClient(ctx context.Context, reqEditors ...RequestEditorFn) (*http.Response, error)
}
// ...
// ClientWithResponsesInterface is the interface specification for the client with responses above.
type ClientWithResponsesInterface interface {
// GetClientWithResponse request
GetClientWithResponse(ctx context.Context, reqEditors ...RequestEditorFn) (*GetClientResponse, error)
// UpdateClientWithResponse request
UpdateClientWithResponse(ctx context.Context, reqEditors ...RequestEditorFn) (*UpdateClientResponse, error)
}
type GetClientResponse struct {
Body []byte
HTTPResponse *http.Response
JSON200 *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/oapi-codegen/oapi-codegen/v2/examples/client"
)
func TestClient_canCall() {
// custom HTTP client
hc := http.Client{}
// with a raw http.Response
{
c, err := client.NewClient("http://localhost:1234", client.WithHTTPClient(&hc))
if err != nil {
log.Fatal(err)
}
resp, err := c.GetClient(context.TODO())
if err != nil {
log.Fatal(err)
}
if resp.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))
if err != nil {
log.Fatal(err)
}
resp, err := c.GetClientWithResponse(context.TODO())
if err != nil {
log.Fatal(err)
}
if resp.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/schemasobject, asoapi-codegenwill 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.0
title: Generate models
paths:
/client:
get:
operationId: getClient
responses:
200:
content:
application/json:
schema:
# NOTE that Client is generated here, because it's within #/components/schemas
$ref: "#/components/schemas/Client"
put:
operationId: updateClient
responses:
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/1512
schema:
type: object
properties:
code:
type: string
required:
- code
components:
schemas:
Client:
type: object
required:
- name
properties:
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: true
Unreferenced:
type: object
required:
- id
properties:
id:
type: integer
And a cfg.yaml:
# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json
package: onlymodels
output: only-models.gen.go
generate:
models: true
And a generate.go:
package onlymodels
//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen -config cfg.yaml api.yaml
This would then generate:
package onlymodels
// Client defines model for Client.
type Client struct {
Name string `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/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json
package: onlymodels
output: only-models.gen.go
generate:
models: true
output-options:
# NOTE that this is only required for the `Unreferenced` type
skip-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:
responses:
200:
description: Success
content:
application/json:
schema:
$ref: '#/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.yaml
openapi: "3.0.0"
info:
version: 1.0.0
title: Admin API
description: The admin-only portion of the API, which has its own separate OpenAPI spec
tags:
- name: admin
description: Admin API endpoints
- name: user
description: API endpoint that pertains to user data
paths:
/admin/user/{id}:
get:
tags:
- admin
- user
summary: Get a user's details
operationId: getUserById
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
200:
description: Success
content:
application/json:
schema:
$ref: '../common/api.yaml#/components/schemas/User'
This references the common spec:
# common/api.yaml
components:
schemas:
User:
type: object
additionalProperties: false
properties:
name:
type: string
required:
- name
So how do we get oapi-codegen to generate our code?
Using a single package with multiple OpenAPI specs
[!TIP] Since
oapi-codegenv2.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 multiple
go generates, and any other configuration files.
To get oapi-codegen's single-package support working, we need multiple calls to oapi-codegen, one call per OpenAPI spec file:
$ 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
This therefore means that we need multiple configuration files, such as cfg-api.yaml:
# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json
package: samepackage
output: server.gen.go
generate:
models: true
chi-server: true
strict-server: true
output-options:
# to make sure that all types are generated
skip-prune: true
import-mapping:
user.yaml: "-"
And then our cfg-user.yaml:
# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json
package: samepackage
output: user.gen.go
generate:
models: true
output-options:
# to make sure that all types are generated
skip-prune: true
From here, oapi-codegen will generate multiple Go files, all within the same package, which can be used to break down your large OpenAPI specifications, and generate only the subsets of code needed for each part of the spec.
Check out the import-mapping/samepackage example for the full code.
Using multiple packages, with one OpenAPI spec per package
To get oapi-codegen's multi-package support working, we need to set up our directory structure:
├── admin
│ ├── cfg.yaml
│ └── generate.go
└── common
├── cfg.yaml
└── generate.go
We could start with our configuration file for our admin API spec:
# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json
# admin/cfg.yaml
package: admin
output: server.gen.go
generate:
models: true
chi-server: true
output-options:
# to make sure that all types are generated
skip-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 the import-mapping:
# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json
package: admin
output: server.gen.go
generate:
models: true
chi-server: true
output-options:
# to make sure that all types are generated
skip-prune: true
import-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
This will then generate the following code:
package admin
import (
// ...
externalRef0 "github.com/oapi-codegen/oapi-codegen/v2/examples/import-mapping/common"
)
// User defines model for User.
type User = externalRef0.User
If you don't want to do this, an alternate option is to use a single package, with multiple OpenAPI spec files for that given package or to bundle your multiple OpenAPI files into a single spec.
Check out the import-mapping/multiplepackages example for the full code.
Modifying the input OpenAPI Specification
Prior to oapi-codegen v2.4.0, users wishing to override specific configuration, for instance taking advantage of extensions such as x-go-type would need to modify the OpenAPI specification they are using.
In a lot of cases, this OpenAPI specification would be produced by a different team to the consumers (or even a different company) and so asking them to make changes like this were unreasonable.
This would lead to the API consumers needing to vendor the specification from the producer (which is our recommendation anyway) and then make any number of local changes to the specification to make it generate code that looks reasonable.
However, in the case that a consumer would update their specification, they would likely end up with a number of merge conflicts.
Now, as of oapi-codegen v2.4.0, it is now possible to make changes to the input OpenAPI specification without needing to modify it directly.
This takes advantage of the OpenAPI Overlay specification, which is a stable specification.
[!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 a proposed modification to the specification which would relax the need for JSON Path as the targeting mechanism.
For instance, let's say that we have the following OpenAPI specification, which provides insight into an internal endpoint that we should not be generating any code for (denoted by x-internal):
openapi: "3.0.0"
info:
version: 1.0.0
title: "Example to indicate how to use the OpenAPI Overlay specification (https://github.com/OAI/Overlay-Specification)"
paths:
/ping:
get:
responses:
'200':
description: pet response
content:
application/json:
schema:
$ref: '#/components/schemas/Pong'
delete:
x-internal: true
responses:
'202':
content: {}
If we were to run oapi-codegen with out-of-the-box functionality, this would then lead to the DELETE endpoint being generated, which we don't want.
Instead, we can define the following overlay.yaml:
overlay: 1.0.0
info:
title: Overlay
version: 0.0.0
actions:
- target: "$"
description: Perform a structural overlay, which can be more readable, as it's clear what the shape of the document is
update:
info:
x-overlay-applied: structured-overlay
paths:
/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
And our configuration file for oapi-codegen:
# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json
package: api
output: ping.gen.go
generate:
models: true
gorilla-server: true
embedded-spec: true
output-options:
overlay:
path: overlay.yaml
This then completely removes the DELETE endpoint before we even start to parse the specification in oapi-codegen, so it's as if your specification was provided without that endpoint.
Additionally, we can override other pieces of metadata, such as the description for operations.
Check out the overlay example for the full code, and some more complex examples.
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: object
properties:
Field:
type: string
nullable: true
required: []
The default behaviour in oapi-codegen is to generate:
type S struct {
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 withS.Field == nil) - does this field have a value? (
S.Field != nil && *S.Field == "123")
As of oapi-codegen v2.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:
type S struct {
// 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 |
|---|---|---|
|
| Override the generated type definition (and optionally, add an import from another package) |
Using the We can see this at play with the following schemas: From here, we now get two different models: You can see this in more detail in the example code. |
|
| Do not add a pointer type for optional fields in structs |
By default, Using the We can see this at play with the following schemas: From here, we now get two different models: You can see this in more detail in the example code. |
|
| Override the generated name of a field or a type |
By default, 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 We can see this at play with the following schemas: From here, we now get two different models: You can see this in more detail in the example code. |
|
| Override the generated name of a type |
By default, 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 We can see this at play with the following schemas: From here, we now get two different models and a type alias: You can see this in more detail in the example code. |
|
| Force the presence of the JSON tag `omitempty` on a field |
In a case that you may want to add the JSON struct tag We can see this at play with the following schemas: From here, we now get two different models: Notice that the You can see this in more detail in the example code. |
|
| When (un)marshaling JSON, ignore field(s) |
By default, However, sometimes, you want to omit fields, which can be done with the We can see this at play with the following schemas: From here, we now get two different models: Notice that the You can see this in more detail in the example code. |
|
| Generate arbitrary struct tags to fields |
If you're making use of a field's struct tags to i.e. apply validation, decide whether something should be logged, etc, you can use We can see this at play with the following schemas: From here, we now get two different models: You can see this in more detail in the example code. |
|
| Override generated variable names for enum constants |
When consuming an enum value from an external system, the name may not produce a nice variable name. Using the We can see this at play with the following schemas: From here, we now get two different forms of the same enum definition. You can see this in more detail in the example code. |
|
| Add a GoDoc deprecation warning to a type |
When an OpenAPI type is deprecated, a deprecation warning can be added in the GoDoc using We can see this at play with the following schemas: From here, we now get two different forms of the same enum definition. Notice that because we've not set You can see this in more detail in the example code. |
|
| Explicitly order struct fields |
Whether you like certain fields being ordered before others, or you want to perform more efficient packing of your structs, the Note that When an OpenAPI type is deprecated, a deprecation warning can be added in the GoDoc using We can see this at play with the following schemas: From here, we now get two different forms of the same type definition. You can see this in more detail in the example code. |
|
| Only honour the `x-go-name` when generating field names |
In some cases, you may not want use the inbuilt options for converting an OpenAPI field name to a Go field name, such as the In this case, you can use This allows you to take a spec such as: And we'll generate: 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 |
|---|---|
[!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-codegendoes 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/oapi-codegen/oapi-codegen/v2/pkg/securityprovider"
)
func main() {
basicAuth, err := securityprovider.NewSecurityProviderBasicAuth("my_user", "my_pass")
if err != nil {
log.Fatal(err)
}
client, err := NewClient("https://....", WithRequestEditorFn(basicAuth.Intercept))
if err != nil {
log.Fatal(err)
}
resp, err := client.GetClient(context.TODO())
if err != 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-templatesconfiguration must exactly match the filename thatoapi-codegenis 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/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json
# ...
output-options:
user-templates:
client-with-responses.tmpl: ./custom-template.tmpl
additional-properties.tmpl: /tmp/foo.bar
typedef.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-codegenexecutions not necessarily being reproducible. It's recommended to vendor (copy) the OpenAPI spec into your codebase and reference it locallySee 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/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 hash
client-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 tag
client-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 branch
client-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 as
raw.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
It's also possible to set the templates inline in the configuration file:
# 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/2257038
client-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: object
required:
- id
properties:
id:
type: integer
# implicit additionalProperties: true
Will generate:
// Thing defines model for Thing.
type Thing struct {
Id int `json:"id"`
}
// with no generated boilerplate nor the `AdditionalProperties` field
Explicit additionalProperties: true
components:
schemas:
Thing:
type: object
required:
- id
properties:
id:
type: integer
# explicit true
additionalProperties: true
Will generate:
// Thing defines model for Thing.
type Thing struct {
Id int `json:"id"`
AdditionalProperties map[string]interface{} `json:"-"`
}
// with generated boilerplate below
Boilerplate
// Getter for additional properties for Thing. Returns the specified
// element and whether it was found
func (a Thing) Get(fieldName string) (value interface{}, found bool) {
if a.AdditionalProperties != nil {
value, found = a.AdditionalProperties[fieldName]
}
return
}
// Setter for additional properties for Thing
func (a *Thing) Set(fieldName string, value interface{}) {
if a.AdditionalProperties == nil {
a.AdditionalProperties = make(map[string]interface{})
}
a.AdditionalProperties[fieldName] = value
}
// Override default JSON handling for Thing to handle AdditionalProperties
func (a *Thing) UnmarshalJSON(b []byte) error {
object := make(map[string]json.RawMessage)
err := json.Unmarshal(b, &object)
if err != nil {
return err
}
if raw, found := object["id"]; found {
err = json.Unmarshal(raw, &a.Id)
if err != nil {
return fmt.Errorf("error reading 'id': %w", err)
}
delete(object, "id")
}
if len(object) != 0 {
a.AdditionalProperties = make(map[string]interface{})
for fieldName, fieldBuf := range object {
var fieldVal interface{}
err := json.Unmarshal(fieldBuf, &fieldVal)
if err != nil {
return fmt.Errorf("error unmarshaling field %s: %w", fieldName, err)
}
a.AdditionalProperties[fieldName] = fieldVal
}
}
return nil
}
// Override default JSON handling for Thing to handle AdditionalProperties
func (a Thing) MarshalJSON() ([]byte, error) {
var err error
object := make(map[string]json.RawMessage)
object["id"], err = json.Marshal(a.Id)
if err != nil {
return nil, fmt.Errorf("error marshaling 'id': %w", err)
}
for fieldName, field := range a.AdditionalProperties {
object[fieldName], err = json.Marshal(field)
if err != nil {
return nil, fmt.Errorf("error marshaling '%s': %w", fieldName, err)
}
}
return json.Marshal(object)
}
additionalProperties as integers
components:
schemas:
Thing:
type: object
required:
- id
properties:
id:
type: integer
# simple type
additionalProperties:
type: integer
Will generate:
// Thing defines model for Thing.
type Thing struct {
Id int `json:"id"`
AdditionalProperties map[string]int `json:"-"`
}
// with generated boilerplate below
Boilerplate
// Getter for additional properties for Thing. Returns the specified
// element and whether it was found
func (a Thing) Get(fieldName string) (value int, found bool) {
if a.AdditionalProperties != nil {
value, found = a.AdditionalProperties[fieldName]
}
return
}
// Setter for additional properties for Thing
func (a *Thing) Set(fieldName string, value int) {
if a.AdditionalProperties == nil {
a.AdditionalProperties = make(map[string]int)
}
a.AdditionalProperties[fieldName] = value
}
// Override default JSON handling for Thing to handle AdditionalProperties
func (a *Thing) UnmarshalJSON(b []byte) error {
object := make(map[string]json.RawMessage)
err := json.Unmarshal(b, &object)
if err != nil {
return err
}
if raw, found := object["id"]; found {
err = json.Unmarshal(raw, &a.Id)
if err != nil {
return fmt.Errorf("error reading 'id': %w", err)
}
delete(object, "id")
}
if len(object) != 0 {
a.AdditionalProperties = make(map[string]int)
for fieldName, fieldBuf := range object {
var fieldVal int
err := json.Unmarshal(fieldBuf, &fieldVal)
if err != nil {
return fmt.Errorf("error unmarshaling field %s: %w", fieldName, err)
}
a.AdditionalProperties[fieldName] = fieldVal
}
}
return nil
}
// Override default JSON handling for Thing to handle AdditionalProperties
func (a Thing) MarshalJSON() ([]byte, error) {
var err error
object := make(map[string]json.RawMessage)
object["id"], err = json.Marshal(a.Id)
if err != nil {
return nil, fmt.Errorf("error marshaling 'id': %w", err)
}
for fieldName, field := range a.AdditionalProperties {
object[fieldName], err = json.Marshal(field)
if err != nil {
return nil, fmt.Errorf("error marshaling '%s': %w", fieldName, err)
}
}
return json.Marshal(object)
}
additionalProperties with an object
components:
schemas:
Thing:
type: object
required:
- id
properties:
id:
type: integer
# object
additionalProperties:
type: object
properties:
foo:
type: string
Will generate:
// Thing defines model for Thing.
type Thing struct {
Id int `json:"id"`
AdditionalProperties map[string]struct {
Foo *string `json:"foo,omitempty"`
} `json:"-"`
}
// with generated boilerplate below
Boilerplate
// Getter for additional properties for Thing. Returns the specified
// element and whether it was found
func (a Thing) Get(fieldName string) (value struct {
Foo *string `json:"foo,omitempty"`
}, found bool) {
if a.AdditionalProperties != nil {
value, found = a.AdditionalProperties[fieldName]
}
return
}
// Setter for additional properties for Thing
func (a *Thing) Set(fieldName string, value struct {
Foo *string `json:"foo,omitempty"`
}) {
if a.AdditionalProperties == nil {
a.AdditionalProperties = make(map[string]struct {
Foo *string `json:"foo,omitempty"`
})
}
a.AdditionalProperties[fieldName] = value
}
// Override default JSON handling for Thing to handle AdditionalProperties
func (a *Thing) UnmarshalJSON(b []byte) error {
object := make(map[string]json.RawMessage)
err := json.Unmarshal(b, &object)
if err != nil {
return err
}
if raw, found := object["id"]; found {
err = json.Unmarshal(raw, &a.Id)
if err != nil {
return fmt.Errorf("error reading 'id': %w", err)
}
delete(object, "id")
}
if len(object) != 0 {
a.AdditionalProperties = make(map[string]struct {
Foo *string `json:"foo,omitempty"`
})
for fieldName, fieldBuf := range object {
var fieldVal struct {
Foo *string `json:"foo,omitempty"`
}
err := json.Unmarshal(fieldBuf, &fieldVal)
if err != nil {
return fmt.Errorf("error unmarshaling field %s: %w", fieldName, err)
}
a.AdditionalProperties[fieldName] = fieldVal
}
}
return nil
}
// Override default JSON handling for Thing to handle AdditionalProperties
func (a Thing) MarshalJSON() ([]byte, error) {
var err error
object := make(map[string]json.RawMessage)
object["id"], err = json.Marshal(a.Id)
if err != nil {
return nil, fmt.Errorf("error marshaling 'id': %w", err)
}
for fieldName, field := range a.AdditionalProperties {
object[fieldName], err = json.Marshal(field)
if err != nil {
return nil, fmt.Errorf("error marshaling '%s': %w", fieldName, err)
}
}
return json.Marshal(object)
}
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.0
title: Example code for the `name-normalizer` output option
paths:
/api/pets/{petId}:
get:
summary: Get pet given identifier.
operationId: getHttpPet
parameters:
- name: petId
in: path
required: true
schema:
type: string
responses:
'200':
description: valid pet
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
components:
schemas:
Pet:
type: object
required:
- uuid
- name
properties:
uuid:
type: string
description: The pet uuid.
name:
type: string
description: The name of the pet.
Error:
required:
- code
- message
properties:
code:
type: integer
format: int32
description: Error code
message:
type: string
description: Error message
OneOf2things:
description: "Notice that the `things` is not capitalised"
oneOf:
- type: object
required:
- id
properties:
id:
type: integer
- type: object
required:
- id
properties:
id:
type: string
format: uuid
This will produce:
// OneOf2things Notice that the `things` is not capitalised
type OneOf2things struct {
union json.RawMessage
}
// Pet defines model for Pet.
type Pet struct {
// Name The name of the pet.
Name string `json:"name"`
// Uuid The pet uuid.
Uuid string `json:"uuid"`
}
// The interface specification for the client above.
type ClientInterface interface {
// GetHttpPet request
GetHttpPet(ctx context.Context, petId string, reqEditors ...RequestEditorFn) (*http.Response, error)
}
Example, using ToCamelCaseWithInitialisms
By default, oapi-codegen will perform camel-case conversion, so for a spec such as:
openapi: "3.0.0"
info:
version: 1.0.0
title: Example code for the `name-normalizer` output option
paths:
/api/pets/{petId}:
get:
summary: Get pet given identifier.
operationId: getHttpPet
parameters:
- name: petId
in: path
required: true
schema:
type: string
responses:
'200':
description: valid pet
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
components:
schemas:
Pet:
type: object
required:
- uuid
- name
properties:
uuid:
type: string
description: The pet uuid.
name:
type: string
description: The name of the pet.
Error:
required:
- code
- message
properties:
code:
type: integer
format: int32
description: Error code
message:
type: string
description: Error message
OneOf2things:
description: "Notice that the `things` is not capitalised"
oneOf:
- type: object
required:
- id
properties:
id:
type: integer
- type: object
required:
- id
properties:
id:
type: string
format: uuid
This will produce:
// OneOf2things Notice that the `things` is not capitalised
type OneOf2things struct {
union json.RawMessage
}
// Pet defines model for Pet.
type Pet struct {
// Name The name of the pet.
Name string `json:"name"`
// UUID The pet uuid.
UUID string `json:"uuid"`
}
// The interface specification for the client above.
type ClientInterface interface {
// GetHTTPPet request
GetHTTPPet(ctx context.Context, petID string, reqEditors ...RequestEditorFn) (*http.Response, error)
}
For more details of what the resulting code looks like, check out the test cases.
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:
- Building a Go RESTful API with design-first OpenAPI contracts
- A Practical Guide to Using oapi-codegen in Golang API Development with the Fiber Framework
- Generating Go server code from OpenAPI 3 definitions
- Go Client Code Generation from Swagger and OpenAPI
- Go oapi-codegen + request validation
- Streamlining Go + Chi Development: Generating Code from an OpenAPI Spec
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.0
title: Using complex schemas
description: An example of `anyOf`, `allOf` and `oneOf`
components:
schemas:
# base types
Client:
type: object
required:
- name
properties:
name:
type: string
Identity:
type: object
required:
- issuer
properties:
issuer:
type: string
# allOf performs a union of all types defined
ClientWithId:
allOf:
- $ref: '#/components/schemas/Client'
- properties:
id:
type: integer
required:
- id
# allOf performs a union of all types defined, but if there's a duplicate field defined, it'll be overwritten by the last schema
# https://github.com/oapi-codegen/oapi-codegen/issues/1569
IdentityWithDuplicateField:
allOf:
# `issuer` will be ignored
- $ref: '#/components/schemas/Identity'
# `issuer` will be ignored
- properties:
issuer:
type: integer
# `issuer` will take precedence
- properties:
issuer:
type: object
properties:
name:
type: string
required:
- name
# anyOf results in a type that has an `AsClient`/`MergeClient`/`FromClient` and an `AsIdentity`/`MergeIdentity`/`FromIdentity` method so you can choose which of them you want to retrieve
ClientAndMaybeIdentity:
anyOf:
- $ref: '#/components/schemas/Client'
- $ref: '#/components/schemas/Identity'
# oneOf results in a type that has an `AsClient`/`MergeClient`/`FromClient` and an `AsIdentity`/`MergeIdentity`/`FromIdentity` method so you can choose which of them you want to retrieve
ClientOrIdentity:
oneOf:
- $ref: '#/components/schemas/Client'
- $ref: '#/components/schemas/Identity'
This results in the following types:
Base types
// Client defines model for Client.
type Client struct {
Name string `json:"name"`
}
// Identity defines model for Identity.
type Identity struct {
Issuer string `json:"issuer"`
}
allOf
// ClientWithId defines model for ClientWithId.
type ClientWithId struct {
Id int `json:"id"`
Name string `json:"name"`
}
// IdentityWithDuplicateField defines model for IdentityWithDuplicateField.
type IdentityWithDuplicateField struct {
Issuer struct {
Name string `json:"name"`
} `json:"issuer"`
}
anyOf
import (
"encoding/json"
"github.com/oapi-codegen/runtime"
)
// ClientAndMaybeIdentity defines model for ClientAndMaybeIdentity.
type ClientAndMaybeIdentity struct {
union json.RawMessage
}
// AsClient returns the union data inside the ClientAndMaybeIdentity as a Client
func (t ClientAndMaybeIdentity) AsClient() (Client, error) {
var body Client
err := json.Unmarshal(t.union, &body)
return body, err
}
// FromClient overwrites any union data inside the ClientAndMaybeIdentity as the provided Client
func (t *ClientAndMaybeIdentity) FromClient(v Client) error {
b, err := json.Marshal(v)
t.union = b
return err
}
// MergeClient performs a merge with any union data inside the ClientAndMaybeIdentity, using the provided Client
func (t *ClientAndMaybeIdentity) MergeClient(v Client) error {
b, err := json.Marshal(v)
if err != nil {
return err
}
merged, err := runtime.JSONMerge(t.union, b)
t.union = merged
return err
}
// AsIdentity returns the union data inside the ClientAndMaybeIdentity as a Identity
func (t ClientAndMaybeIdentity) AsIdentity() (Identity, error) {
var body Identity
err := json.Unmarshal(t.union, &body)
return body, err
}
// FromIdentity overwrites any union data inside the ClientAndMaybeIdentity as the provided Identity
func (t *ClientAndMaybeIdentity) FromIdentity(v Identity) error {
b, err := json.Marshal(v)
t.union = b
return err
}
// MergeIdentity performs a merge with any union data inside the ClientAndMaybeIdentity, using the provided Identity
func (t *ClientAndMaybeIdentity) MergeIdentity(v Identity) error {
b, err := json.Marshal(v)
if err != nil {
return err
}
merged, err := runtime.JSONMerge(t.union, b)
t.union = merged
return err
}
func (t ClientAndMaybeIdentity) MarshalJSON() ([]byte, error) {
b, err := t.union.MarshalJSON()
return b, err
}
func (t *ClientAndMaybeIdentity) UnmarshalJSON(b []byte) error {
err := t.union.UnmarshalJSON(b)
return err
}
oneOf
// AsClient returns the union data inside the ClientOrIdentity as a Client
func (t ClientOrIdentity) AsClient() (Client, error) {
var body Client
err := json.Unmarshal(t.union, &body)
return body, err
}
// FromClient overwrites any union data inside the ClientOrIdentity as the provided Client
func (t *ClientOrIdentity) FromClient(v Client) error {
b, err := json.Marshal(v)
t.union = b
return err
}
// MergeClient performs a merge with any union data inside the ClientOrIdentity, using the provided Client
func (t *ClientOrIdentity) MergeClient(v Client) error {
b, err := json.Marshal(v)
if err != nil {
return err
}
merged, err := runtime.JSONMerge(t.union, b)
t.union = merged
return err
}
// AsIdentity returns the union data inside the ClientOrIdentity as a Identity
func (t ClientOrIdentity) AsIdentity() (Identity, error) {
var body Identity
err := json.Unmarshal(t.union, &body)
return body, err
}
// FromIdentity overwrites any union data inside the ClientOrIdentity as the provided Identity
func (t *ClientOrIdentity) FromIdentity(v Identity) error {
b, err := json.Marshal(v)
t.union = b
return err
}
// MergeIdentity performs a merge with any union data inside the ClientOrIdentity, using the provided Identity
func (t *ClientOrIdentity) MergeIdentity(v Identity) error {
b, err := json.Marshal(v)
if err != nil {
return err
}
merged, err := runtime.JSONMerge(t.union, b)
t.union = merged
return err
}
func (t ClientOrIdentity) MarshalJSON() ([]byte, error) {
b, err := t.union.MarshalJSON()
return b, err
}
func (t *ClientOrIdentity) UnmarshalJSON(b []byte) error {
err := t.union.UnmarshalJSON(b)
return err
}
For more info, check out the example code.
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/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json
output-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.
Contributors
We're very appreciative of the many contributors over the years and the ongoing use of the project 💜
Sponsors
For the most part, oapi-codegen is maintained in two busy peoples' free time. As noted in Creating a more sustainable model for oapi-codegen in the future, we're looking to make this a more sustainable project in the future.
Please consider sponsoring us through GitHub Sponsors either on the organisation or directly for Jamie, which helps work towards us being able to maintain the project long term.
See this blog post from Tidelift for more details on how to talk to your company about sponsoring maintainers of (Open Source) projects you depend on.
We are currently sponsored for 4 hours of work a month by Elastic:
In addition, we are also generously sponsored by the following folks, each of whom provide sponsorship for 1 hour of work a month:
(Note that the order of appearance the order in which sponsorship was received)