fix: remove optional object properties from required array when using @nestjs/swagger v7 (#371)

Author: 55Kamiryo

packages/nestjs-zod/package.json

@@ -64,6 +64,7 @@
     "@nestjs/common": "^11.1.5",
     "@nestjs/core": "^11.1.5",
     "@nestjs/swagger": "^11.2.0",
+    "@nestjs/swagger-v7": "npm:@nestjs/swagger@7.4.2",
     "@nestjs/testing": "^11.1.12",
     "@stoplight/spectral-core": "^1.22.0",
     "@stoplight/spectral-rulesets": "^1.22.1",

packages/nestjs-zod/src/__e2e_tests__/openapi.test.ts

@@ -20,6 +20,7 @@ import {
 import z from 'zod/v4';
 import { createZodDto } from '../dto';
 import { SwaggerModule } from '@nestjs/swagger';
+import { SwaggerModule as SwaggerModuleV7 } from '@nestjs/swagger-v7';
 import { cleanupOpenApiDoc } from '../cleanupOpenApiDoc';
 import get from 'lodash/get';
 import { PREFIX } from '../const';
@@ -3122,6 +3123,44 @@ describe('issue#368', () => {
   });
 });
 
+describe('issue#371 - optional object properties in @nestjs/swagger version 7', () => {
+  test('does not include optional object as a required field', async () => {
+    class BodyDto extends createZodDto(
+      z.object({
+        name: z.string(),
+        filter: z
+          .object({
+            age: z.number(),
+          })
+          .optional(),
+      }),
+    ) {}
+
+    @Controller()
+    class TestController {
+      constructor() {}
+
+      @Post()
+      create(@Body() _body: BodyDto) {
+        return {};
+      }
+    }
+
+    const doc = await getSwaggerDoc(TestController, {
+      swaggerVersion: '7',
+    });
+
+    expect(get(doc, 'components.schemas.BodyDto.required')).toEqual(['name']);
+    expect(
+      get(doc, 'components.schemas.BodyDto.properties.filter'),
+    ).not.toHaveProperty('selfRequired');
+    expect(JSON.stringify(doc)).not.toContain(PREFIX);
+
+    expect(await getOpenApiErrors(doc, '3.0')).toHaveLength(0);
+    expect(await getOpenApiErrors(doc, '3.1')).toHaveLength(0);
+  });
+});
+
 async function createApp(controllerClass: Type<unknown>) {
   @Module({
     imports: [],
@@ -3142,15 +3181,20 @@ async function getSwaggerDoc(
   {
     cleanUp = true,
     version,
+    swaggerVersion,
   }: {
     cleanUp?: boolean;
     version?: '3.1' | '3.0' | 'auto';
+    swaggerVersion?: '7' | 'default';
   } = {},
 ) {
   const app = await createApp(controllerClass);
 
-  const doc = SwaggerModule.createDocument(app, new DocumentBuilder().build());
+  const doc = (
+    swaggerVersion === '7' ? SwaggerModuleV7 : SwaggerModule
+  ).createDocument(app, new DocumentBuilder().build());
   if (cleanUp) {
+    // @ts-expect-error - FIXME
     return cleanupOpenApiDoc(doc, { version });
   } else {
     return doc;

packages/nestjs-zod/src/cleanupOpenApiDoc.ts

@@ -309,11 +309,29 @@ function cleanupSchema({
     oldOpenapiSchema,
   );
 
-  for (const propertySchema of Object.values(
+  for (const [propertyName, propertySchema] of Object.entries(
     newOpenapiSchema.properties || {},
   )) {
     if (SELF_REQUIRED_KEY in propertySchema) {
+      // @nestjs/swagger v7 has a bug where `required` is not set properly when
+      // one of the parameters is an optional object
+      if (
+        !propertySchema[SELF_REQUIRED_KEY] &&
+        Array.isArray(newOpenapiSchema.required)
+      ) {
+        const idx = newOpenapiSchema.required.indexOf(propertyName);
+        if (idx !== -1) {
+          newOpenapiSchema.required.splice(idx, 1);
+        }
+        if (newOpenapiSchema.required.length === 0) {
+          delete newOpenapiSchema.required;
+        }
+      }
       delete propertySchema[SELF_REQUIRED_KEY];
+
+      if ('selfRequired' in propertySchema) {
+        delete propertySchema.selfRequired;
+      }
     }
 
     if (USES_THREE_POINT_ONE_SYNTAX_KEY in propertySchema) {

packages/nestjs-zod/src/const.ts

@@ -5,6 +5,6 @@ export const PARENT_ID_KEY = `${PREFIX}-parent-id`;
 export const PARENT_ADDITIONAL_PROPERTIES_KEY = `${PREFIX}-parent-additional-properties`;
 export const PARENT_HAS_REFS_KEY = `${PREFIX}-parent-has-refs`;
 export const UNWRAP_ROOT_KEY = `${PREFIX}-unwrap-root`;
-export const USES_THREE_POINT_ONE_SYNTAX_KEY = `${PREFIX}-uses-3.1-syntax`;
+export const USES_THREE_POINT_ONE_SYNTAX_KEY = `${PREFIX}-uses-3-point-1-syntax`;
 export const SELF_REQUIRED_KEY = `${PREFIX}-self-required`;
 export const PARENT_METADATA_KEY = `${PREFIX}-parent-metadata`;