Skip to content

Generated API Documentation#

Huma uses the OpenAPI spec to generate interactive API documentation using third-party tools. By default, Stoplight Elements is used to render the documentation at the API's config.DocsPath which defaults to /docs.

You can switch to other documentation renderers using config.DocsRenderer. The following renderers are supported out of the box:

  • huma.DocsRendererStoplightElements (default)
  • huma.DocsRendererScalar
  • huma.DocsRendererSwaggerUI

Stoplight Elements

Disabling the Docs

You can disable the built-in documentation by setting config.DocsPath to an empty string, then register your own route on the underlying router. The DocsRenderer* functions in api.go show what to return.

Middleware Conflicts

Some middleware can interfere with the documentation renderer's ability to fetch the OpenAPI spec. For example, go-chi/chi's middleware.URLFormat will rewrite URLs that end in .json or .yaml (e.g. /openapi.json -> /openapi), which can lead to 404 errors for the spec. If you encounter this, consider disabling that middleware or configuring it to skip the OpenAPI and documentation paths.

Customizing Documentation#

Each renderer accepts its own options through config.DocsRendererConfig. Set it to any value that marshals to JSON (a map[string]any is easiest), and Huma writes it into the docs HTML. Scalar and SwaggerUI support it; Stoplight Elements ignores it.

Scalar Docs#

Scalar Docs provide a featureful and customizable API documentation experience that feels similar to Postman in your browser.

code.go
router := chi.NewRouter()
config := huma.DefaultConfig("Docs Example", "1.0.0")
config.DocsRenderer = huma.DocsRendererScalar

// Optional. Scalar reads these from the `data-configuration` attribute. See
// https://github.com/scalar/scalar/blob/main/documentation/configuration.md
config.DocsRendererConfig = map[string]any{
	"theme":      "mars", // one of: default, alternate, moon, purple, solarized, ...
	"hideModels": true,   // hide the models section
}

api := humachi.New(router, config)

Scalar Docs

Stoplight Elements#

Stoplight Elements is the default renderer, so you get it without setting config.DocsRenderer at all. It doesn't read config.DocsRendererConfig.

code.go
router := chi.NewRouter()
config := huma.DefaultConfig("Docs Example", "1.0.0")

api := humachi.New(router, config)

Stoplight Elements Stacked

SwaggerUI#

SwaggerUI is an older but proven documentation generator that is widely used in the industry. It provides a more traditional API documentation experience.

code.go
router := chi.NewRouter()
config := huma.DefaultConfig("Docs Example", "1.0.0")
config.DocsRenderer = huma.DocsRendererSwaggerUI

// Optional. These fields are merged into the SwaggerUIBundle config object. See
// https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
config.DocsRendererConfig = map[string]any{
	"defaultModelsExpandDepth": -1,   // hide the models section
	"tryItOutEnabled":          true, // enable "Try it out" by default
}

api := humachi.New(router, config)

SwaggerUI

Dive Deeper#