[openapi] A handler cannot declare its own status codes or content types #76

Problem

Field report from porting a ~60-route application (remote-hand) from @hono/zod-openapi to gotcha 0.4.1.

A route cannot declare the status codes it actually returns. POST /api/accounts answers 201 on success and 409 on a duplicate; GET /api/sessions/{id} answers 404. gotcha derives exactly one success response, always 200, and folds a Result's error side into a single default entry — so all three of those routes document the same thing, and the generated TypeScript client is wrong about every one of them.

Three separate walls, all in gotcha_core-0.4.1/src/responsible.rs:

1. The success status is hardcoded. json_response::<T>() inserts the key "200" (responsible.rs:29-45). There is no 201, no 204, no way to say otherwise.

2. A type cannot be both Schematic and custom-Responsible. impl<T: Schematic> Responsible for T (responsible.rs:82-96) is a blanket. A local wrapper that does not implement Schematic can carry its own Responsible — verified, that compiles. But the moment it also derives Schematic (which is how you get the body type into components), you get:

   error[E0119]: conflicting implementations of trait `Responsible` for type `Created<_>`
   note: conflicting implementation in crate `gotcha_core`:
         - impl<T> Responsible for T where T: Schematic;
   

   And the hand-written path is bare: json_response is private (responsible.rs:23), so implementing Responsible yourself means constructing oas::Responses / Response / MediaType / Referenceable by hand, with no helper exposed and no example anywhere in the crate.

3. default is mandatory and unremovable. impl<E: Schematic> ErrorResponsible for E unconditionally does responses.default = Some(..) (responsible.rs:128-132). A Result<Json<T>, ApiError> handler always gets a default entry, even when the real contract is a specific 404.

4. The content type is always application/json. The same json_response::<T>() hardcodes the media-type key (responsible.rs:34). A file-download route serving application/octet-stream has no way to say so.

#33 closed on "a Result<Json<T>, ApiError> handler documents both the success and the error response", which does work. Its own Direction section also listed "Let handlers / #[api] declare status codes and per-response descriptions" — that half did not land, and it is the half a real application needs.

Where

• gotcha_core-0.4.1/src/responsible.rs:29-45 — "200" hardcoded
• gotcha_core-0.4.1/src/responsible.rs:82-96 — blanket impl<T: Schematic> Responsible for T
• gotcha_core-0.4.1/src/responsible.rs:128-132 — default unconditionally set

How remote-hand works around it

Two modules, both pure workaround:

• server-rs/src/api/created.rs — a Created<T> wrapper that implements IntoResponse as (StatusCode::CREATED, Json(..)) and delegates Schematic to T, so the derived response is right about the body and wrong about the status. Delegating Schematic is what forecloses a custom Responsible (point 2 above), and hand-rolling one would have meant hand-rolling oas::Responses.
• server-rs/src/openapi_ext.rs — a declarative registry of (method, path, status) -> body type patches applied in the single allowed GotchaRouter::openapi(|spec| ..) pass. It inserts the missing 404/409, moves the derived 200 to 201, and carries a drop_default flag whose only job is deleting the default entry gotcha insists on.

For the octet-stream case, server-rs/src/files/mod.rs wraps the response in a FileBytes newtype with a hand-written Schematic that registers no component (type: string, format: binary), and the same registry swaps the JSON 200 for the application/octet-stream entry.

A test (server-rs/tests/probe.rs) asserts the patches took effect, because nothing else would catch it if an upgrade changed the derivation.

Suggested direction

• An #[api(responses(404 = ApiError, 409 = ApiError))] form on the handler attribute, merged into the derived responses.
• A status-carrying return wrapper in gotcha itself (Created<T>, WithStatus<T, const S: u16>) so the success key is not always "200".
• Either narrow the blanket Responsible impl or provide an explicit escape hatch, so downstream crates can describe their own response types — which would also cover non-JSON bodies.
• A way to suppress the default entry when the handler enumerates its errors explicitly.