Customise the spec and docs paths¶

By default Register serves the spec at /openapi.yaml and the docs UI at /docs/, titled "API documentation". Override any of these with options.

Version the routes under a prefix¶

openapi.Register(mux, spec,
    openapi.WithSpecPath("/v1/openapi.yaml"),
    openapi.WithDocsPath("/v1/docs/"),
    openapi.WithTitle("Acme API v1"),
)

The docs page points at whatever WithSpecPath resolves to, so the two stay in sync automatically — you only set the paths, the UI is wired to them.

Serve several API versions from one server¶

Each Register call is independent, so registering more than one pair of paths on the same mux exposes several versions side by side:

if err := openapi.Register(mux, specV1,
    openapi.WithSpecPath("/v1/openapi.yaml"),
    openapi.WithDocsPath("/v1/docs/"),
    openapi.WithTitle("Acme API v1"),
); err != nil {
    return err
}

if err := openapi.Register(mux, specV2,
    openapi.WithSpecPath("/v2/openapi.yaml"),
    openapi.WithDocsPath("/v2/docs/"),
    openapi.WithTitle("Acme API v2"),
); err != nil {
    return err
}

Every path must be distinct. Two calls that share a spec path or a docs path panic — ServeMux refuses to register the same pattern twice, and the panic happens inside the second Register call rather than coming back as an error. Calling Register twice with the defaults is the easy way to hit this.

Why does a docs path without a trailing slash panic?¶

WithDocsPath must end in a slash: /docs/, not /docs.

The exact path serves the generated index page and the subtree below it serves the embedded JavaScript and CSS, which is expressed as two ServeMux patterns — GET /docs/{$} and GET /docs/. Drop the trailing slash and the first becomes GET /docs{$}, which is not a valid pattern, so ServeMux panics while parsing it:

panic: parsing "GET /docs{$}": at offset 5: bad wildcard segment (must start with '{')

Register does not validate the path first, so this is what a missing slash looks like. The options reference lists the other path mistakes that behave the same way. Spec paths have no trailing-slash rule, but both paths must be absolute — a leading / is required.

Set the browser tab title¶

openapi.Register(mux, spec, openapi.WithTitle("Payments API"))

The title appears in the browser tab of the docs page. It does not affect the spec, and it is not the API title shown in the page itself — that comes from info.title in your OpenAPI document. Set both if you want them to agree.