Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(openapi): declare the 400 on every route that takes a body

Yudhi Armyndharisa3b124a9ca73
diff --git a/src/config/swagger.config.spec.ts b/src/config/swagger.config.spec.ts
index 75f889eac..d1970fee4 100644
--- a/src/config/swagger.config.spec.ts
+++ b/src/config/swagger.config.spec.ts
@@ -9,7 +9,7 @@ import {
PUBLIC_PATHS,
METRICS_BEARER_SCHEME,
} from './swagger.config';
-import type { OpenAPIObject } from '@nestjs/swagger';
+import type { OpenAPIObject, OperationObject } from '@nestjs/swagger';
import { EnginePageError } from '../common/errors/engine-page.error';
describe('createSwaggerConfig', () => {
@@ -145,6 +145,23 @@ describe('documentErrorResponses', () => {
);
});
+ // The global ValidationPipe (whitelist + forbidNonWhitelisted) and the JSON body parser answer 400
+ // before the handler runs, so every operation that takes a body can return one.
+ it('adds a 400 to an operation that takes a request body, keeping its own when it has one', () => {
+ const doc = fixtureDoc();
+ const body = { content: { 'application/json': { schema: { type: 'object' } } } };
+ doc.paths['/api/sessions'].post!.requestBody = body;
+ doc.paths['/api/sessions'].put = { requestBody: body, responses: { '400': { description: 'Name taken' } } };
+ doc.paths['/api/sessions'].get = { responses: { '200': { description: 'ok' } } };
+ const paths = documentErrorResponses(doc).paths['/api/sessions'];
+ const description = (op: OperationObject | undefined): string | undefined =>
+ (op?.responses['400'] as { description: string } | undefined)?.description;
+ expect(description(paths.post)).toMatch(/does not declare/);
+ expect(paths.post!.responses['400']).toEqual(expect.objectContaining({ content: ref }));
+ expect(description(paths.put)).toBe('Name taken');
+ expect(description(paths.get)).toBeUndefined();
+ });
+
it('leaves operations with their own security as they were', () => {
const before = fixtureDoc();
const after = documentErrorResponses(fixtureDoc());
diff --git a/src/config/swagger.config.ts b/src/config/swagger.config.ts
index baf7708d8..dcf810b75 100644
--- a/src/config/swagger.config.ts
+++ b/src/config/swagger.config.ts
@@ -147,9 +147,10 @@ const ERROR_RESPONSE: SchemaObject = {
const AUTH_FORBIDDEN = "API key's role, session or chat scope, or IP allow-list does not allow this operation";
/**
- * Give every API-key operation its auth refusals and a schema for its error bodies. An operation
- * with its own `security` (the @Public routes and the metrics scrape) is skipped: those answer
- * their own shapes, such as the health probe's 503. Existing responses keep their descriptions,
+ * Give every API-key operation its auth refusals, a 400 when it takes a body (the JSON parser and the
+ * global ValidationPipe refuse one before the handler runs), and a schema for its error bodies. An
+ * operation with its own `security` (the @Public routes and the metrics scrape) is skipped: those
+ * answer their own shapes, such as the health probe's 503. Existing responses keep their descriptions,
* except that an operation's own 403 also gets the auth refusal, which the guard can answer there
* too. Idempotent. Mutates and returns the document.
*/
@@ -162,6 +163,11 @@ export function documentErrorResponses(document: OpenAPIObject): OpenAPIObject {
const op = (item as Record<string, OperationObject | undefined>)[method];
if (!op || op.security !== undefined) continue;
op.responses['401'] ??= { description: 'The API key is missing, unknown, revoked, or expired' };
+ if (op.requestBody) {
+ op.responses['400'] ??= {
+ description: 'The body is malformed, fails validation, or carries a field the DTO does not declare',
+ };
+ }
const forbidden = op.responses['403'];
if (!forbidden) {
op.responses['403'] = { description: `The ${AUTH_FORBIDDEN}` };