Options reference¶

Every option Register accepts, what it defaults to, and what happens when it is wrong. The authoritative per-symbol API — signatures and doc comments — lives on pkg.go.dev.

Register¶

func Register(mux *http.ServeMux, spec []byte, opts ...Option) error

Mounts the spec and the docs UI on mux. See the routes reference for the exact patterns, methods and status codes.

Register mounts routes and returns; it does not start a server. The docs page HTML is rendered once, at registration time, from the resolved options.

When Register returns an error¶

Only if the embedded asset filesystem cannot be opened or the index template cannot be executed. Both are build-time constants, so in practice the returned error is always nil.

Handle it anyway. It is the signature's contract — and the failure that is plausible, a malformed path, does not come back through it. It panics. See what happens when a path is wrong.

Options¶

Option	Default	Effect
`WithSpecPath(p string)`	`/openapi.yaml`	path the spec bytes are served at
`WithDocsPath(p string)`	`/docs/`	path prefix for the UI — must end in `/`
`WithTitle(t string)`	`API documentation`	the docs page `<title>`
`WithSecurityHeaderOptions(opts ...transporthttp.SecurityHeadersOption)`	conservative defaults	customise the security-header middleware
`WithoutSecurityHeaders()`	(headers on)	remove the built-in security-header wrapper

Options are applied in the order supplied, so passing the same one twice keeps the last value. WithSecurityHeaderOptions is the exception: it appends to the list of header options rather than replacing it, so repeated calls accumulate.

WithSpecPath¶

The path the raw OpenAPI document is served from. It is also written into the generated docs page as the apiDescriptionUrl attribute, so the UI always points at the path you set — the two cannot drift apart.

It must be an absolute path beginning with /. It does not have to sit outside the docs prefix: WithSpecPath("/docs/openapi.yaml") alongside the default docs path works, because the exact spec pattern is more specific than the docs subtree pattern and wins.

WithDocsPath¶

The prefix the UI is served from. It must end in a slash. The exact path serves the generated index page; everything below it serves the embedded JavaScript and CSS, and those asset URLs are built by concatenating the prefix with the file name.

WithDocsPath("/") is legal and serves the UI at the site root, with the spec route still reachable because it is the more specific pattern.

WithTitle¶

Sets the <title> of the generated page — what the browser tab shows. It has no effect on the spec, and no effect on the API title Stoplight renders in the page body, which comes from info.title in your OpenAPI document. Set both if you want them to match.

The value is HTML-escaped, so a title containing markup is rendered as text rather than injected into the page.

WithSecurityHeaderOptions¶

Forwards go/transport/http SecurityHeadersOption values verbatim to transporthttp.SecurityHeadersMiddleware, which wraps the docs and spec handlers. The full upstream header policy is reachable through it — see Configure security headers for the options and their defaults.

Supplying this option does not switch the middleware on. It is on already; this only changes how it is configured.

WithoutSecurityHeaders¶

Replaces the security-header middleware with a pass-through, so the docs, spec and asset routes are served with no X-Content-Type-Options, X-Frame-Options, Content-Security-Policy or Referrer-Policy at all.

It also cancels WithSecurityHeaderOptions — the middleware those options configure is never constructed, whichever order the two are supplied in.

Use it only where an outer chain sets equivalent headers. Otherwise you are serving an interactive console that can be framed and MIME-sniffed.

Defaults¶

Without options, Register(mux, spec) serves:

GET /openapi.yaml → the spec bytes, Content-Type: application/yaml
GET /docs/ → the Stoplight UI, titled "API documentation"
GET /docs/{asset} → the embedded web-components.min.js and styles.min.css

All three carry go/transport's default security headers: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Content-Security-Policy: frame-ancestors 'none', Referrer-Policy: no-referrer, and HSTS off.

What happens when a path is wrong¶

Register builds net/http routing patterns from the paths you give it and hands them to mux.Handle. ServeMux rejects a malformed pattern by panicking, and Register does no validation of its own, so a bad path takes the process down at registration time rather than returning an error.

Mistake	Result
`WithDocsPath("/docs")` — no trailing slash	panic: `parsing "GET /docs{$}": at offset 5: bad wildcard segment (must start with '{')`
`WithDocsPath("")`	panic: `parsing "GET {$}": at offset 4: host/path missing /`
`WithSpecPath("openapi.yaml")` — no leading slash	panic: `parsing "GET openapi.yaml": at offset 4: host/path missing /`
Two `Register` calls sharing a spec or docs path	panic: `pattern "GET /openapi.yaml" … conflicts with pattern "GET /openapi.yaml"`
A path your own handlers already registered on the mux	the same conflict panic

This is loud and immediate — it happens during startup, not under traffic — but it is a panic, not an error. If your paths come from configuration rather than literals, validate them before calling Register: absolute, and slash-terminated for the docs prefix.

Version compatibility with go/transport¶

This module depends on gitlab.com/phpboyscout/go/transport for the security-header middleware and on gitlab.com/phpboyscout/go/transit for the Middleware type. The versions a release is built and tested against are the ones in go.mod — currently go/transport v0.3.0 and go/transit v0.1.3.

The two version lines are not paired minor-for-minor. They move independently: transport-openapi v0.1.x is built against go/transport v0.3.x. What matters is that your build resolves one go/transport whose SecurityHeadersOption type is the one this module was compiled against — which Go's minimum version selection gives you as long as you do not pin go/transport below the version in go.mod.

Both modules are pre-1.0, so a minor bump upstream may change that API. If you pass WithSecurityHeaderOptions, upgrade the two together and rebuild.