Oapi-codegen

External

• https://github.com/deepmap/oapi-codegen

Internal

• Go OpenAPI
• OpenAPI Operation Declaration and Implementation Examples

Overview

Rewrite this after using it for two different services.

Installation

Get the latest version from https://github.com/deepmap/oapi-codegen/tags

Then:

go install github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen@v2.1.0

The installation will place the package under $GOPATH/pkg/mod/cache/download/github.com/deepmap and $GOPATH/pkg/mod/github.com/deepmap, will compile the binary and place it under ~/go/bin.

Generate Code

Generate client and server code:

oapi-codegen -package petstore ./petstore-expanded.yaml > ./internal/petstore/petstore.gen.go
go mod tidy

The types, spec and server code can live in different packages. For suggestions on layout, see:

Go Project Layout

Makefile Support

.PHONY: generate_oapi_artifacts

generate_oapi_artifacts: internal/petstore/spec.gen.go internal/petstore/types.gen.go internal/petstore/server.gen.go internal/petstore/client.gen.go

internal/petstore/spec.gen.go: ./petstore.yaml
	oapi-codegen -generate spec -package petstore $< > $@

internal/petstore/types.gen.go: ./petstore.yaml
	oapi-codegen -generate types -package petstore $< > $@

internal/petstore/server.gen.go: ./petstore.yaml
	oapi-codegen -generate server -package petstore $< > $@

internal/petstore/client.gen.go: ./petstore.yaml
	oapi-codegen -generate client -package petstore $< > $@

Type Generation

Generate the types declared in the /components/schemas section of the OpenAPI specification.

oapi-codegen -generate types -package petstore ./petstore-expanded.yaml > ./api/openapi-types.gen.go

Also see:

OpenAPI Specification Schemas

Server Code Generation

https://github.com/deepmap/oapi-codegen#generated-server-boilerplate

TODO:

• Understand and document "strict server"

By default, oapi-codegen generates server code for the echo HTTP server.

oapi-codegen -generate server -package petstore ./petstore.yaml > ./internal/petstore/server.gen.go

For an example of how to set up an echo server with the generated code, see:

echo Server with oapi-codegen Code

For OpenAPI specification examples and their corresponding generated server code see:

OpenAPI Examples

Client Code Generation

https://github.com/deepmap/oapi-codegen#generated-client-boilerplate

The client code must be generated in the same package as the generated types, because it refers to them. See Type Generation above.

oapi-codegen -generate types -package api ./petstore-expanded.yaml > ./api/openapi-types.gen.go
oapi-codegen -generate client -package api ./petstore-expanded.yaml > ./api/openapi-client.gen.go

The generator creates ClientInterface and ClientWithResponsesInterface interfaces. TODO: Understand and document the difference?

Options

-package

The package name for the generated code.

-generate

Comma-separated list of code to generate; valid options: "types", "client", "chi-server", "server", "gin", "gorilla", "spec", "skip-fmt", "skip-prune", "fiber", "iris". The default is "types,client,server,spec".

types

See Type Generation above.

server

See Server Code Generation above.

chi-server

Generates server code for the chi HTTP server. The code is compatible with net/http server:

oapi-codegen -generate chi-server -package petstore ./petstore.yaml > ./internal/petstore/server.gen.go

For an example of how to set up a net/http server with the generated code, see:

net/http Server with oapi-codegen Code

client

See Client Code Generation above.

spec

TODO: what is this and how it is useful?

Generates this:

var swaggerSpec = []string{...}

func decodeSpec() ([]byte, error) {...}

var rawSpec = decodeSpecCached()

func decodeSpecCached() func() ([]byte, error) {...}

func PathToRawSpec(pathToFile string) map[string]func() ([]byte, error) {...}

func GetSwagger() (swagger *openapi3.T, err error) {...}