Summary

Fixes #3862 — regression introduced in 11.2.7 via PR #3803.

PR #3803 added a guard that suppresses the auto-inferred default response whenever any Api*Response decorator is present. The guard doesn't distinguish success (2xx) from error (4xx/5xx) decorators, so a handler with only @ApiUnauthorizedResponse() (or any other error-status decorator) loses its auto-inferred 2xx in the OpenAPI spec. Downstream client generators (NSwag, openapi-generator, ...) then treat the real 2xx response as an exception at runtime.

This PR scopes the guard to decorators whose status code is below 400 so error factories no longer suppress the default. The redirect case the original PR fixed (@ApiFoundResponse on a @Redirect() handler) continues to work — 302 is still below 400.

Approach

Named Api*Response factories — status codes are derived from the decorator name via the same Api${PascalCase(HttpStatus key)}Response convention the factories are generated from in api-response.decorator.ts. Unknown names (ApiDefaultResponse, user-defined Api*Response) fall back to the previous behavior (treated as explicit), so no existing explicit-response pattern regresses.

Mirrors the forward-direction idiom in api-response.decorator.ts:148:

// forward: generating factories
.filter((key) => !isNaN(Number(HttpStatus[key])))
// reverse: decoder in this PR
const status = Number(HttpStatus[statusKey as keyof typeof HttpStatus]);
return isNaN(status) || status < 400;

Plain @ApiResponse({ status }) — the status argument is inspected: numeric literals (status: 500), the shorthand strings '1XX'/'2XX'/'3XX', and 'default' are classified by their code. Non-literal expressions (e.g. HttpStatus.OK) can't be evaluated at compile time and keep the pre-PR behavior (treated as explicit).

Behavior matrix

Tests

• New fixture test/plugin/fixtures/app.controller-api-response-error.ts covering five scenarios:
  • @Post + @ApiUnauthorizedResponse alone
  • @Get + @ApiNotFoundResponse alone
  • @Post + @ApiCreatedResponse + @ApiUnauthorizedResponse (explicit success, default still suppressed)
  • @Post + @ApiResponse({ status: 500 }) alone (arg-inspection case)
  • @Get + @Redirect + @ApiFoundResponse (Adding @ApiFoundResponse on a dynamic redirect method still renders a 200 response code in the OpenAPI contract #1639 preservation)
• New regression test in controller-class-visitor.spec.ts (named after Regression in 11.2.7: plugin drops auto-inferred 2xx response when only error @Api*Response decorators are present (PR #3803) #3862).
• Existing Adding @ApiFoundResponse on a dynamic redirect method still renders a 200 response code in the OpenAPI contract #1639 fixture (app.controller-api-response.ts) still passes — redirect case preserved.
• Existing app.controller fixture updated: its create() handler uses multiple error-status @ApiResponse decorators and the expected output had baked in the 11.2.7 regression. Now expects the restored pre-11.2.7 behavior (default 201 alongside the error entries).
• Full test suite: 274/274 passing. npm run lint clean on changed files. prettier --check clean on changed files.

Disclaimers

• Transparency: this PR was prepared in collaboration with an AI coding assistant. I reviewed and approved every change. Happy to iterate on feedback.
• Given the subtlety of the 11.2.7 regression (silent OpenAPI spec diff, only surfaces in downstream client generators), reviewers may want to independently verify no other response-generation paths are affected.