Schemas and security

Understand the limits of inference and explicitly define custom request/response contracts.

Typed action signatures can generate much of the OpenAPI document. When using custom extractors, raw bodies, or custom responses, however, you need to complete it with explicit metadata.

Automatic inference#

Typed path/query/header/body/multipart parameters and explicit response wrappers contribute to contract generation. Result<String, E> is a JSON string, while direct String is a text response; this runtime response distinction also appears in OpenAPI.

Cases requiring explicit metadata#

Case	What to check
Custom extractor	Parameter or request body contract
Raw body	Media type and schema
Manual or passthrough response	Status, headers, and response schema
Streaming, SSE, or static files	Media type and specialized response behavior
Custom response converter	Actual bodies of success and error responses

Define parameters, request_body, and responses metadata for these paths. ToResponse and IntoResponses support reusable response contracts. Keep operation IDs stable and unique; summary, description, and deprecated fields complete the explanation.

Security schemes#

Register bearer, API key, or OpenID Connect schemes with OpenApiConfig::register_security_scheme. Actions inherit controller security metadata. Empty security() is an explicit override for a public action.

Metadata does not authenticate. A security scheme describes a requirement in the document. Enforce actual identity and permission checks with #[guard(...)].

Build validation#

Duplicate operation IDs/paths/components, unresolved references, and security errors are rejected during build. Nonstandard HTTP methods require openapi(skip); they are not treated as new fields outside OpenAPI's path-item method fields.

The guide's complete OpenAPI example is a small starting point for this setup. Keep each custom contract current by comparing it with example requests and responses.