feat(@nestjs/swagger): Support extensions in Document and Schema objects

Author: drewish

e2e/api-spec.json

@@ -1085,6 +1085,10 @@
             ]
           }
         },
+        "x-tags": [
+          "foo",
+          "bar"
+        ],
         "required": [
           "name",
           "age",

e2e/src/cats/dto/create-cat.dto.ts

@@ -1,9 +1,10 @@
-import { ApiExtraModels, ApiProperty } from '../../../../lib';
+import { ApiExtension, ApiExtraModels, ApiProperty } from '../../../../lib';
 import { ExtraModel } from './extra-model.dto';
 import { LettersEnum } from './pagination-query.dto';
 import { TagDto } from './tag.dto';
 
 @ApiExtraModels(ExtraModel)
+@ApiExtension('x-tags', ['foo', 'bar'])
 export class CreateCatDto {
   @ApiProperty()
   readonly name: string;

lib/document-builder.ts

@@ -1,5 +1,5 @@
 import { Logger } from '@nestjs/common';
-import { isString, isUndefined, negate, pickBy } from 'lodash';
+import { clone, isString, isUndefined, negate, pickBy } from 'lodash';
 import { buildDocumentBase } from './fixtures/document.base';
 import { OpenAPIObject } from './interfaces';
 import {
@@ -85,6 +85,18 @@ export class DocumentBuilder {
     return this;
   }
 
+  public addExtension(extensionKey: string, extensionProperties: any): this {
+    if (!extensionKey.startsWith('x-')) {
+      throw new Error(
+        'Extension key is not prefixed. Please ensure you prefix it with `x-`.'
+      );
+    }
+
+    this.document[extensionKey] = clone(extensionProperties);
+
+    return this;
+  }
+
   public addSecurity(name: string, options: SecuritySchemeObject): this {
     this.document.components.securitySchemes = {
       ...(this.document.components.securitySchemes || {}),

lib/services/schema-object-factory.ts

@@ -204,11 +204,13 @@ export class SchemaObjectFactory {
     if (!propertiesWithType) {
       return '';
     }
+    const extensionProperties = Reflect.getMetadata(DECORATORS.API_EXTENSION, type) || [];
     const typeDefinition: SchemaObject = {
       type: 'object',
       properties: mapValues(keyBy(propertiesWithType, 'name'), (property) =>
         omit(property, ['name', 'isArray', 'required', 'enumName'])
-      ) as Record<string, SchemaObject | ReferenceObject>
+      ) as Record<string, SchemaObject | ReferenceObject>,
+      ...extensionProperties
     };
     const typeDefinitionRequiredFields = propertiesWithType
       .filter((property) => property.required != false)

test/services/schema-object-factory.spec.ts

@@ -1,4 +1,4 @@
-import { ApiProperty } from '../../lib/decorators';
+import { ApiExtension, ApiProperty } from '../../lib/decorators';
 import { SchemasObject } from '../../lib/interfaces/open-api-spec.interface';
 import { ModelPropertiesAccessor } from '../../lib/services/model-properties-accessor';
 import { SchemaObjectFactory } from '../../lib/services/schema-object-factory';
@@ -297,6 +297,20 @@ describe('SchemaObjectFactory', () => {
         properties: { name: { type: 'string', minLength: 1 } }
       });
     });
+
+    it('should include extension properties', () => {
+      @ApiExtension('x-test', 'value')
+      class CreatUserDto {
+        @ApiProperty({ minLength: 0, required: true })
+        name: string;
+      }
+
+      const schemas: Record<string, SchemasObject> = {};
+
+      schemaObjectFactory.exploreModelSchema(CreatUserDto, schemas);
+
+      expect(schemas[CreatUserDto.name]['x-test']).toEqual('value');
+    });
   });
 
   describe('createEnumSchemaType', () => {