Troubleshooting

Troubleshooting

The UI loads but shows "Failed to load API definition"

The browser could not fetch OpenAPIPath. It is resolved by the browser, not by the server, so:

curl -si http://localhost:8080/openapi.json | head -1

• 404 — the OpenAPI extension is not registered, or its ServePath differs from the UI's OpenAPIPath.
• Works in curl, fails in the browser — a cross-origin fetch. The origin serving the document has to allow the UI's origin; see rextension-cors.
• A different router — a document served on an internal listener is not reachable from a browser on the public one.

/apidoc 404s but /apidoc/ works

It should not — a redirect from ServePath to ServePath + "/" is registered automatically. If the bare path 404s, check for a conflicting route on the same path, which the framework reports at startup as a duplicate.

Nothing is registered at all

• The extension is not in the option list.
• WithSwagger(&swagger.Config{…}) with a partial literal — ServePath is then "". Use swagger.NewConfig(...).

Assets 404

Assets are served relative to ServePath, so changing it moves them too. If you are reverse-proxying the UI under a different prefix, the page's asset URLs will not match — mount it at the same path the proxy exposes, or use the router's BaseURL so the framework rewrites consistently.

The page loads unstyled

• DefaultTheme names a theme that was never registered. The UI still works, with the base stylesheet only.
• A custom theme's CSS is empty — WithCustomTheme(name, nil) registers nothing.

My custom theme has no effect

• Selector specificity. Prefix rules with .swagger-ui; the UI's own rules are specific and unprefixed selectors usually lose.
• It is not the default theme. WithCustomTheme registers it; WithDefaultTheme selects it.

The Required Authorization panel is missing

• The route does not implement RequiredRoles(), so there is no x-required-roles in the document.
• The map key does not match a name in RequiredSchemes().
• The security extension is not registered, so no schemes are documented.

Check the document directly:

curl -s localhost:8080/openapi.json | jq '.paths["/users/{id}"].delete."x-required-roles"'

Operations are missing from the UI

That is an OpenAPI question, not a Swagger one — the UI renders what the document contains. A route has to implement OpenAPIRoute to appear, and be on an included router. See rextension-openapi → Troubleshooting.

"Try it out" requests fail with a CORS error

The UI is served from one origin and calling another. Allow the UI's origin on the API:

cors.WithAllowedOrigins("https://docs.example.com")

If both are the same application on the same router, there is no cross-origin request and something else is wrong — check the browser's network tab for the actual failing request.

The UI is reachable in production

That is a deployment decision, and usually the wrong one: the UI publishes your entire API surface and invites people to call it. Register the extension conditionally, or serve it on an internal router. See Configuration.

Upgrading Swagger UI

The assets are embedded at build time — swagger.SwaggerUIVersion reports which version. Upgrading means upgrading this module; there is no runtime override, which is deliberate: a UI loading scripts from a CDN is a third-party script with full access to the page a developer pastes bearer tokens into.