Troubleshooting

Troubleshooting

My route is missing from the document

In order of likelihood:

1. It does not implement OpenAPIRoute. That is the opt-in switch — all four methods are required.
2. Pointer receiver, value registration. func (r *CreateUser) Summary() needs app.RegisterRoute(&CreateUser{…}).
3. It is on a router that is not included. IncludeRouters is empty by default, which means the default router only. Add the router, or use "*".
4. It was registered after the tables were frozen. The framework refuses that now, so you would have seen an error from Run.

The application fails to start with an OpenAPI error

The document is generated in ValidateRoutes, at startup — so a generation failure fails the boot rather than producing a 500 on every request to the spec path. The error names what went wrong.

Schemas are missing from operations

The route does not implement RequestBody() / Responses(). Those come from rextension.BodySchemaProvider, the same interface the validation extension reads.

If they are implemented and still missing, check the receiver again — a pointer method on a value registration fails silently everywhere.

components/schemas has odd or colliding names

The component key is the Go type name, so two types with the same name in different packages collide. Rename one, or wrap it in a distinctly-named type.

A field is missing from a schema

• json:"-" omits it.
• An unexported field is invisible to reflection.
• A field of type interface{} or any has no static type to reflect on and produces an untyped object.

Security schemes are absent

The generator resolves rextension.SchemeRegistry from the container. If the security extension is not registered, or registers no schemes, there is nothing to document — and nothing fails, because an API without authentication is a legitimate thing to document.

If security is configured and the schemes are still missing, check that nothing is calling the deprecated package-level RegisterSecuritySchemes.

An operation has no security block but should

The route does not implement RequiredSchemes(). That also means it is not being enforced — the security middleware reads the same interface. Reviewing the generated document for missing security blocks is a cheap way to catch routes someone forgot to secure.

x-required-roles is missing

The route does not implement RequiredRoles(), or the map key does not match a name in RequiredSchemes(). The security extension makes that mismatch a startup error, so if the application boots, the key is probably just absent.

An internal route leaked into the public document

IncludeRouters defaults to the default router only — but if you set "*", use ExcludeRouters for the private ones:

openapi.WithIncludeRouters("*"),
openapi.WithExcludeRouters("internal", "metrics", "health"),

And check whether that route should be implementing OpenAPIRoute at all.

The document is empty

• No route implements OpenAPIRoute.
• IncludeRouters names a router that does not exist — that matches nothing and is not an error.

example vs examples

The generator emits the OpenAPI 3.1 examples map, not the deprecated singular example property. If a tool is not showing your examples, check that it supports 3.1 rather than 3.0.

The document changed and nobody noticed

Generate it in a test and compare against a checked-in snapshot:

doc, err := openapi.NewGenerator(cfg, nil).Generate(routes())

An accidental contract change then fails CI instead of reaching a client.

Swagger UI shows nothing

The UI has to point at the path the document is actually served at, on a router it can reach. Confirm with curl:

curl -s localhost:8080/openapi.json | head