When working with services, it can be convienient to embed the openapi spec and the SwaggerUI tool into your server so that you can eaily explore your API during development.
This tool is designed to function alongside deepmap/oapi-codegen to embed the data required in to create routes that expose your OpenAPI spec and the SwaggerUI tool.
Using the following go:generate
directives will generate an embedded spec and a swaggerui file
using the provided OpenAPI spec (it's recommended to use gobin
for reproducible/consistent builds).
//go:generate gobin -m -run github.com/pseudo-su/oapi-ui-codegen/cmd/oapi-ui-codegen --package=main --generate spec -o ./spec.gen.go ./openapi.yaml
//go:generate gobin -m -run github.com/pseudo-su/oapi-ui-codegen/cmd/oapi-ui-codegen --package=main --generate swaggerui -o ./swagger_ui.gen.go ./openapi.yaml
A working example can also be found here for reference pseudo-su/golang-service-template
The default options for oapi-ui-codegen
will generate the swagger spec and swagger-ui
files, but you can generate subsets of those via the -generate
flag. It defaults to spec,swaggerui
.
spec
: embed the OpenAPI spec into the generated code as a gzipped blob.swaggerui
: embed the SwaggerUI html pages into the generated code as a gzipped blob.skip-fmt
: skip runninggo fmt
on the generated code. This is useful for debugging the generated file in case the spec contains weird strings.
So, for example, if you would like to produce only the embedded spec, you could
run oapi-ui-generate --generate spec
.