Skip to content

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.

crates/features/src/posts/http/controller.rs
#[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 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 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:

crates/features/src/posts/http/controller.rs
#[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.

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.

crates/features/src/audio/http/controller.rs
#[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.

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:

crates/features/src/notifications/http/controller.rs
#[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.

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.

nest_rs::health (the probes' routes)
#[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.

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:

crates/features/src/sign_in/http/controller.rs (from the demo, abridged)
#[post("/login")]
// …
#[api(summary = "Sign in with email and password", tags("Auth"))]
async fn login(&self, Json(input): Json<LoginDto>) -> Result<AccessTokenResponse> {
// …
}

deprecated = "YYYY-MM-DD" deprecates a route for its clients, from the date it took effect:

crates/features/src/posts/http/controller.rs
#[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 OK
deprecation: @1791417600

The 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.