fix(openapi-spec): honor declared success statuses in generated responses

.changeset/calm-status-contracts.md

@@ -0,0 +1,8 @@
+---
+"@croco/protocols-core": patch
+"@croco/openapi-spec": patch
+"@croco/transports-http": patch
+---
+
+- Keep declared route success statuses consistent across extraction, OpenAPI responses, and HTTP output.
+- Preserve legacy 200 JSON and 204 empty responses when no status is declared, and reject response schemas on body-forbidden statuses.

packages/docs/src/content/docs/api/protocols-core/src/interfaces/RouteIR.md

@@ -1,3 +1,3 @@
 ---
 editUrl: false
 next: false
@@ -83,4 +83,4 @@
 
 > `optional` **successStatus?**: `number`
 
-Declared successful HTTP status. Defaults to 200 for legacy RouteIR artifacts.
+Declared successful HTTP status. Omitted when the route does not declare one.

packages/openapi-spec/src/libs/emitOpenAPI.ts

@@ -1,3 +1,3 @@
 import {
   extendZodWithOpenApi,
   OpenAPIRegistry,
@@ -150,7 +150,11 @@
       : {}),
   };
 
-  assertContractGraphConsumerRouteCoverage(graph, "openapi", collectOpenAPICoveredRoutes(document));
+  assertContractGraphConsumerRouteCoverage(
+    graph,
+    "openapi",
+    collectOpenAPICoveredRoutes(document, routes),
+  );
 
   return document;
 }
@@ -288,25 +292,26 @@
   problemDetailsRef: OpenAPIReference,
 ): RouteResponses {
   const outputSchema = unwrapZodEffectsSchema(route.outputSchema);
+  const successStatus = getSuccessStatus(route);
   const responses = {
     ...defaultResponses,
     ...toDeclaredProblemResponseConfig(route, problemDetailsRef),
   };
-  if (!outputSchema) delete responses[200];
-
   return {
     ...responses,
-    ...(outputSchema
+    [successStatus]: outputSchema
       ? {
-          200: {
-            description: "Successful response",
-            content: { "application/json": { schema: outputSchema } },
-          },
+          description: "Successful response",
+          content: { "application/json": { schema: outputSchema } },
         }
-      : { 204: { description: "No content" } }),
+      : { description: "No content" },
   };
 }
 
+function getSuccessStatus(route: ContractGraphRoute): number {
+  return route.successStatus ?? (route.outputSchema ? 200 : 204);
+}
+
 function toDeclaredProblemResponseConfig(
   route: ContractGraphRoute,
   problemDetailsRef: OpenAPIReference,
@@ -498,8 +503,10 @@
 
 function collectOpenAPICoveredRoutes(
   document: OpenAPIDocument,
+  routes: readonly ContractGraphRoute[],
 ): ContractGraphObservedConsumerRoute[] {
   const coveredRoutes: ContractGraphObservedConsumerRoute[] = [];
+  const routesById = new Map(routes.map((route) => [route.routeId, route]));
 
   for (const [path, pathItem] of Object.entries(document.paths ?? {})) {
     if (!isRecord(pathItem)) {
@@ -529,7 +536,9 @@
           "request.path": hasOpenAPIParameters(operation, "path") ? "present" : "absent",
           "request.query": hasOpenAPIParameters(operation, "query") ? "present" : "absent",
           "request.headers": hasOpenAPIParameters(operation, "header") ? "present" : "absent",
-          response: hasOpenAPIJsonSuccessResponse(operation) ? "present" : "absent",
+          response: hasOpenAPIJsonSuccessResponse(operation, routesById.get(operation["summary"]))
+            ? "present"
+            : "absent",
           problems: openAPIProblemsFingerprint(operation),
           entitlements: openAPIEntitlementsFingerprint(operation),
         },
@@ -581,9 +590,12 @@
     .some((parameter) => parameter.in === location && typeof parameter.name === "string");
 }
 
-function hasOpenAPIJsonSuccessResponse(operation: Record<string, unknown>): boolean {
+function hasOpenAPIJsonSuccessResponse(
+  operation: Record<string, unknown>,
+  route: ContractGraphRoute | undefined,
+): boolean {
   const responses = isRecord(operation.responses) ? operation.responses : {};
-  const successResponse = responses["200"];
+  const successResponse = route ? responses[String(getSuccessStatus(route))] : undefined;
 
   if (!isRecord(successResponse) || !isRecord(successResponse.content)) {
     return false;

packages/openapi-spec/src/tests/emitOpenAPI.spec.ts

@@ -25,7 +25,9 @@ import {
   ProblemResponse,
   Query,
   RequestValidationProblem,
+  REST_ROUTES_KEY,
   ResponseSchema,
+  type RouteMetadata,
   type RouteBody,
   type RouteMethodReturn,
 } from "@croco/protocols-rest";
@@ -626,6 +628,79 @@ describe("emitOpenAPI", () => {
     });
   });
 
+  it("should emit a declared 201 JSON success without an inferred 200", () => {
+    const createdSchema = z.object({ id: z.string() });
+
+    @Controller("/orders")
+    class OrdersController {
+      @Post("/")
+      @ResponseSchema(createdSchema)
+      createOrder(): z.infer<typeof createdSchema> {
+        return { id: "order-1" };
+      }
+    }
+
+    const metadata = Reflect.getMetadata(REST_ROUTES_KEY, OrdersController) as RouteMetadata[];
+    const route = metadata[0];
+    if (!route) throw new TypeError("Expected order route metadata.");
+    route.statusCode = 201;
+
+    const responses = emitOpenAPI([OrdersController]).paths?.["/orders"]?.post?.responses;
+
+    expect(responses?.[201]).toMatchObject({
+      content: { "application/json": { schema: { properties: { id: { type: "string" } } } } },
+    });
+    expect(responses?.[200]).toBeUndefined();
+  });
+
+  it("should reject a non-success status before it can replace a Problem response", () => {
+    @Controller("/orders")
+    class OrdersController {
+      @Post("/")
+      createOrder(): void {}
+    }
+
+    const metadata = Reflect.getMetadata(REST_ROUTES_KEY, OrdersController) as RouteMetadata[];
+    const route = metadata[0];
+    if (!route) throw new TypeError("Expected order route metadata.");
+    route.statusCode = 404;
+
+    expect(() =>
+      emitOpenAPI([OrdersController], {
+        problemResponses: [{ status: 404, description: "Order not found" }],
+      }),
+    ).toThrow(/contract-route-invalid-success-status/);
+  });
+
+  it("should keep a declared bodyless success status and reject a body on 204 or 205", () => {
+    @Controller("/orders")
+    class OrdersController {
+      @Post("/accepted")
+      acceptOrder(): void {}
+
+      @Post("/invalid")
+      @ResponseSchema(z.object({ id: z.string() }))
+      invalidOrder(): void {}
+    }
+
+    const metadata = Reflect.getMetadata(REST_ROUTES_KEY, OrdersController) as RouteMetadata[];
+    const accepted = metadata.find((route) => route.methodName === "acceptOrder");
+    const invalid = metadata.find((route) => route.methodName === "invalidOrder");
+    if (!accepted || !invalid) throw new TypeError("Expected order route metadata.");
+    accepted.statusCode = 202;
+    invalid.statusCode = 204;
+
+    expect(() => emitOpenAPI([OrdersController])).toThrow(/contract-route-body-forbidden-status/);
+
+    invalid.statusCode = 205;
+    expect(() => emitOpenAPI([OrdersController])).toThrow(/contract-route-body-forbidden-status/);
+
+    invalid.statusCode = 201;
+    const responses = emitOpenAPI([OrdersController]).paths?.["/orders/accepted"]?.post?.responses;
+    expect(responses?.[202]).toEqual({ description: "No content" });
+    expect(responses?.[204]).toBeUndefined();
+  });
+
   it("should emit request and response contracts from one route schema object", () => {
     const createUserRoute = defineRouteSchema({
       request: {
@@ -843,7 +918,7 @@ describe("emitOpenAPI", () => {
       },
     });
     expect(responses?.[429]).toEqual({ description: "Too many requests" });
-    expect(responses?.[200]).toBeUndefined();
+    expect(responses?.[200]).toEqual({ description: "Inherited success response" });
     expect(responses?.[204]).toEqual({ description: "No content" });
   });
 

packages/openapi-spec/src/tests/round-trip.spec.ts

@@ -16,12 +16,14 @@ import {
   Post,
   ProblemResponse,
   Query,
+  REST_ROUTES_KEY,
   ResponseSchema,
 } from "@croco/protocols-rest";
 import { describe, expect, it } from "vitest";
 import { z } from "zod";
 import { createApp } from "../../../transports-http/src/libs/CrocoApp";
 import { emitOpenAPI } from "../libs/emitOpenAPI";
+import type { RouteMetadata } from "@croco/protocols-rest";
 
 type User = {
   readonly id: number;
@@ -56,6 +58,13 @@ type GeneratedUsersClient = {
   }>;
 };
 
+type GeneratedCreatedClient = {
+  readonly createdControllerCreateWidget: (options?: RequestInit) => Promise<{
+    readonly data: { readonly id: string };
+    readonly status: number;
+  }>;
+};
+
 type OpenAPIDocument = ReturnType<typeof emitOpenAPI>;
 type OpenAPIPathItem = NonNullable<OpenAPIDocument["paths"]>[string];
 type OpenAPIOperation = NonNullable<OpenAPIPathItem>["post"];
@@ -128,6 +137,87 @@ describe("OpenAPI round trip", () => {
     },
   );
 
+  it(
+    "should preserve an explicit 201 response through extraction, OpenAPI, client generation, and HTTP transport",
+    { timeout: 30000 },
+    async () => {
+      @Controller("/created")
+      class CreatedController {
+        @Post("/widgets")
+        @ResponseSchema(z.object({ id: z.string() }))
+        createWidget(): { id: string } {
+          return { id: "widget-1" };
+        }
+      }
+
+      const metadata = Reflect.getMetadata(REST_ROUTES_KEY, CreatedController) as RouteMetadata[];
+      const createRoute = metadata.find((route) => route.methodName === "createWidget");
+      if (!createRoute) {
+        throw new TypeError("Expected metadata for CreatedController.createWidget.");
+      }
+      createRoute.statusCode = 201;
+
+      const routes = extractRouteIR(CreatedController);
+      const spec = emitOpenAPI([CreatedController]);
+      const operation = readOperation(spec, "post", "/created/widgets");
+      const app = createApp({
+        controllers: [CreatedController],
+        diValidation: "off",
+        securityValidation: "off",
+      });
+      const tempDirectory = mkdtempSync(join(tmpdir(), "openapi-created-roundtrip-"));
+      const specPath = join(tempDirectory, "openapi.json");
+      const clientPath = join(tempDirectory, "client.ts");
+      const originalFetch = globalThis.fetch;
+
+      try {
+        expect(routes).toHaveLength(1);
+        expect(routes[0]?.successStatus).toBe(201);
+        expect(operation.responses?.[200]).toBeUndefined();
+        expect(operation.responses?.[201]).toMatchObject({
+          content: {
+            "application/json": {
+              schema: expect.objectContaining({
+                properties: expect.objectContaining({
+                  id: expect.objectContaining({ type: "string" }),
+                }),
+              }),
+            },
+          },
+        });
+
+        writeFileSync(specPath, JSON.stringify(spec, null, 2));
+        runOrval(specPath, clientPath);
+        expect(readFileSync(clientPath, "utf8")).toContain(
+          "data: CreatedControllerCreateWidget201",
+        );
+
+        globalThis.fetch = (input, init) => {
+          if (typeof input !== "string" || !input.startsWith("/")) {
+            return originalFetch(input, init);
+          }
+          return app.fetch(new Request(`http://localhost${input}`, init));
+        };
+        const client = (await import(pathToFileURL(clientPath).href)) as GeneratedCreatedClient;
+        const response = await client.createdControllerCreateWidget();
+
+        expect(response.status).toBe(201);
+        expect(response.data).toEqual({ id: "widget-1" });
+        assertRuntimeResponseMatchesOpenAPI(
+          spec,
+          operation,
+          "/created/widgets",
+          response.status,
+          "application/json",
+          response.data,
+        );
+      } finally {
+        globalThis.fetch = originalFetch;
+        rmSync(tempDirectory, { force: true, recursive: true });
+      }
+    },
+  );
+
   it("should validate generated operations against real runtime responses", async () => {
     @Controller("/round-trip")
     class RoundTripController {

packages/protocols-core/src/libs/ContractGraph.ts

@@ -1,3 +1,3 @@
 import "reflect-metadata";
 import {
   createProblemRegistrySnapshot,
@@ -448,6 +448,7 @@
   diagnostics.push(...validatePathParams(route));
   diagnostics.push(...validateNamedParams(route));
   diagnostics.push(...validateBodyParams(route));
+  diagnostics.push(...validateSuccessStatus(route));
   diagnostics.push(...validateRouteContract(route));
   diagnostics.push(...validateBindingContractSchemas(route));
   diagnostics.push(...validateStrictSchemas(route, options));
@@ -459,6 +460,37 @@
   return diagnostics;
 }
 
+function validateSuccessStatus(route: ContractGraphRoute): ContractDiagnostic[] {
+  if (
+    route.successStatus !== undefined &&
+    (!Number.isInteger(route.successStatus) ||
+      route.successStatus < 200 ||
+      route.successStatus > 299)
+  ) {
+    return [
+      createRouteDiagnostic(
+        route,
+        "contract-route-invalid-success-status",
+        "error",
+        `Success status ${route.successStatus} must be an integer between 200 and 299.`,
+      ),
+    ];
+  }
+
+  if ((route.successStatus !== 204 && route.successStatus !== 205) || !route.outputSchema) {
+    return [];
+  }
+
+  return [
+    createRouteDiagnostic(
+      route,
+      "contract-route-body-forbidden-status",
+      "error",
+      `Success status ${route.successStatus} cannot have a response schema because HTTP forbids a response body.`,
+    ),
+  ];
+}
+
 function validateStrictSchemas(
   route: ContractGraphRoute,
   options: BuildContractGraphOptions,

packages/protocols-core/src/libs/RouteIR.ts

@@ -17,7 +17,7 @@ export interface RouteIR {
   inputSchema: z.ZodType | null;
   inputSchemas: RouteInputSchemas;
   outputSchema: z.ZodType | null;
-  /** Declared successful HTTP status. Defaults to 200 for legacy RouteIR artifacts. */
+  /** Declared successful HTTP status. Omitted when the route does not declare one. */
   successStatus?: number;
   problemResponses?: readonly ProblemResponseIR[];
   domain: string | null;

packages/protocols-core/src/libs/extractRouteIR.ts

@@ -70,7 +70,7 @@ export function extractRouteIR(controllerCtor: Constructor): RouteIR[] {
       inputSchema: inputSchemas.body,
       inputSchemas,
       outputSchema,
-      successStatus: routeMeta.statusCode ?? 200,
+      ...(routeMeta.statusCode === undefined ? {} : { successStatus: routeMeta.statusCode }),
       problemResponses,
       domain: null,
     };