OpenAPI operations
What a handler declares beyond its signature — the payload it builds, bodies that are not JSON, its own error bodies, its tags and its deprecation.
The signature carries most of an operation: path, method, parameters, request body, success status and payload. This page covers the rest, each piece written once on the handler and read by the document, the route and the generated client alike.
#[get("/archive")]#[authorize(Read, PostEntity)]#[api( summary = "Every post at once", response = Vec<Post>, deprecated = "2026-10-08",)]async fn archive(&self) -> Result<Response> { /* ... */ }The payload a handler builds itself
Section titled “The payload a handler builds itself”The payload is read off the return type, by its type: a Json<T> documents
T, bare, inside a Created<…> or a Paginated<…>, inside a Result — a
use nest_rs::http::Result as Answer or a type Made = Created<Json<Hook>>
documents the same body. So does a typed answer that renders its own JSON: a
route returning Result<AccessTokenResponse> documents the token response.
What a typed answer sends beside its body is read the same way: a Created<T>
documents its 201 and its Location, a Paginated<T> its Link — which is
why neither the generated #[crud] create nor its list needs an
#[api(response = …)].
response = Type is for a handler that builds its own Response, whose type
names no body. It wins over what the return type says, so it never needs to
restate a typed answer.
A status the handler computes
Section titled “A status the handler computes”A type states its status: a body answers 200, a Created<T> its 201. What
only the handler knows — a (StatusCode, Json<T>) pair, a bare StatusCode, a
built Response, an answer of your own — is documented under 2XX, the range
OpenAPI offers for a status the document cannot name, with the body the pair or
response = Type says:
#[post("/{id}/publish")]async fn publish(&self, Path(id): Path<Uuid>) -> Result<(StatusCode, Json<Post>)> { let (post, already) = self.svc.publish(id).await?; let status = if already { StatusCode::OK } else { StatusCode::ACCEPTED }; Ok((status, Json(post)))}A generated client reads 2XX as the success it is. A handler that always answers
one status says so with #[http_code(N)], which the
document names and every success answers; a status outside the range is one of
your own error bodies.
A handler returning a bare ProblemDetails, alone or in a Result, answers no
success at all: the document lists none, and the problem under 4XX and 5XX,
OpenAPI’s ranges for an error whose status only the handler knows.
Bodies that are not JSON
Section titled “Bodies that are not JSON”A handler returning text or bytes declares nothing: the document reads the media
type off the return type, bare, in a (StatusCode, B) pair, a Created<B>, a
Paginated<B> or a Result — text/plain for a String or a &'static str,
application/octet-stream for Bytes or a Vec<u8>, and */* for a Body, which
sets none — and a #[response_header("content-type", "…")]
keys the body on what it writes instead.
multipart = Type and response_content_type = "…" describe a body no type
states — an upload form, a streamed download. A handler taking RawBody or Body
declares nothing: the document says */*, optional and binary, since it reads
any bytes under any media type or none.
#[post("/uploads/direct")]#[api( summary = "Upload an audio file directly as multipart/form-data", multipart = DirectUploadDto,)]async fn upload_direct(&self, upload: UploadedAudio) -> Result<Json<PresignedUrlDto>> { /* ... */ }
#[get("/download")]#[http_code(200)]#[api( summary = "Stream a transcoded object back through the server", response_content_type = "audio/mpeg",)]async fn download(&self, Query(query): Query<TranscodeDto>) -> Result<Response> { /* ... */ }The form’s parts are a type like any other payload — a String field carrying
#[schemars(extend("format" = "binary"))] is the file part Swagger UI renders a
file picker for. That type documents the form, and nothing reads a request
with it: the extractor taking the parts (UploadedAudio here) is written
apart, so a part renamed in one must be renamed in the other. A handler that takes
nest_rs::http::Multipart directly and declares nothing still documents
multipart/form-data with a free-form object: the media type it accepts is
knowledge a client needs, even when no type states the parts.
A Form<T> on a #[get] reads the query, as a form on GET does, so the document
lists its properties as in: query parameters, with the 400 a value can be refused
with and nothing of a body.
response_content_type replaces what the return type says on the success
response and, with no response = Type beside it, types the body the way OpenAPI
spells a stream — string with format: binary, or plain string for a text/*
media type. An #[sse] route needs no annotation: it answers
text/event-stream and nothing else, so the document reads the media type off
the decorator — and declaring response_content_type there is a compile error.
Header parameters
Section titled “Header parameters”A handler that reads headers binds them as a DTO — Header<T>, the header-map
twin of Query<T> — and each property becomes an in: header parameter, an
Option<_> field being an optional one:
#[input]pub struct StreamResumeDto { #[serde(rename = "Last-Event-ID")] pub last_event_id: Option<u32>,}
#[sse("/events")]async fn events(&self, resume: Header<StreamResumeDto>) -> SseStream { /* ... */ }A missing required header, or a value that does not parse into its field’s type,
is rejected with the same RFC 9457 400 every other edge rejection carries —
naming the header and never quoting its value, because that is where credentials
travel. Any parameter makes the operation advertise that 400, an optional one
and a path’s included, since each can carry a value its type does not read.
Error bodies of your own
Section titled “Error bodies of your own”Every error status the framework answers is a problem document, and the
document lists the ones an operation can produce. A handler that answers a
status with a body of its own declares it with error(status = Type), 4xx or
5xx alone. The health probes are the framework’s own case: a failing probe
answers 503 with the same report an orchestrator reads on success.
#[get("/ready")]#[public]#[api( summary = "Readiness probe: whether the process can take traffic", error(503 = ProbeReport),)]async fn ready(&self) -> ProbeReport { /* ... */ }The body is documented as application/json, beside the problem document when
the framework can answer that status too, so a generated client types both.
Ability-shaped responses
Section titled “Ability-shaped responses”Every wire row a route answers is judged for its caller, whatever its posture names,
and the published schema says exactly what any of them can hold: every key required,
a column a grant may withhold nullable, its description saying so — Field-level
authorization applies: reads null where the caller’s ability withholds it. The
sentence sits on the row’s own schema, so every route answering the row carries it,
inside a list, a page or a DTO, and so do GraphQL’s SDL and an MCP tool’s output
schema; the response keeps its status’s description.
A tag groups operations in Swagger UI’s sidebar and names the class or file a
generator emits them into. Every route of a controller defaults to its
token — PostsController is posts, the stem its operationIds carry — so
a #[crud] controller and the routes written beside it share one group.
tags(...) replaces it on an operation:
#[post("/login")]// …#[api(summary = "Sign in with email and password", tags("Auth"))]async fn login(&self, Json(input): Json<LoginDto>) -> Result<AccessTokenResponse> { // …}Deprecate a route
Section titled “Deprecate a route”deprecated = "YYYY-MM-DD" deprecates a route for its clients, from the date it
took effect:
#[get("/archive")]#[api( description = "Use `GET /posts?first=100`.", deprecated = "2026-10-08",)]async fn archive(&self) -> Result<Response> { /* ... */ }The operation is deprecated: true in the document — a generated client marks
the call @deprecated — and every answer of the route, a guard’s refusal
included, carries the RFC 9745 header a client can watch for:
HTTP/1.1 200 OKdeprecation: @1791417600The value is a date because the header is one: a version ("7.1") is a
compile error. Rust’s own #[deprecated] on a handler or a controller is
refused too — it deprecates the method for Rust callers, and the framework is
the only one — and the refusal names deprecated = "…". A handler’s Err is
rendered past the route and carries no header.
Going further
Section titled “Going further”- OpenAPI — what the document derives, and its limits.
- Typed TypeScript clients — what a frontend generates from it.
- Versioning — serve the replacement beside the deprecated route.