feat(@nestjs/swagger): Allow custom schema naming

You can use @ApiSchema to set a custom schema name.
Custom schema names are not inherited.

lib/constants.ts

@@ -13,5 +13,6 @@ export const DECORATORS = {
   API_EXCLUDE_ENDPOINT: `${DECORATORS_PREFIX}/apiExcludeEndpoint`,
   API_EXCLUDE_CONTROLLER: `${DECORATORS_PREFIX}/apiExcludeController`,
   API_EXTRA_MODELS: `${DECORATORS_PREFIX}/apiExtraModels`,
-  API_EXTENSION: `${DECORATORS_PREFIX}/apiExtension`
+  API_EXTENSION: `${DECORATORS_PREFIX}/apiExtension`,
+  API_SCHEMA: `${DECORATORS_PREFIX}/apiSchema`
 };

lib/decorators/api-schema.decorator.ts

@@ -0,0 +1,20 @@
+import { DECORATORS } from '../constants';
+import { SchemaObjectMetadata } from '../interfaces/schema-object-metadata.interface';
+import { createClassDecorator, createPropertyDecorator } from './helpers';
+
+export interface ApiSchemaOptions extends Pick<SchemaObjectMetadata, 'name'> {
+  /**
+   * Name of the schema.
+   */
+  name: string;
+}
+
+export function ApiSchema(options: ApiSchemaOptions): ClassDecorator {
+  return createApiSchemaDecorator(options);
+}
+
+export function createApiSchemaDecorator(
+  options: ApiSchemaOptions
+): ClassDecorator {
+  return createClassDecorator(DECORATORS.API_SCHEMA, [options]);
+}

lib/decorators/index.ts

@@ -23,3 +23,4 @@ export * from './api-response.decorator';
 export * from './api-security.decorator';
 export * from './api-use-tags.decorator';
 export * from './api-extension.decorator';
+export * from './api-schema.decorator';

lib/services/schema-object-factory.ts

@@ -11,6 +11,7 @@ import {
   pick
 } from 'lodash';
 import { DECORATORS } from '../constants';
+import { ApiSchemaOptions } from '../decorators';
 import { getTypeIsArrayTuple } from '../decorators/helpers';
 import { exploreGlobalApiExtraModelsMetadata } from '../explorers/api-extra-models.explorer';
 import {
@@ -203,8 +204,16 @@ export class SchemaObjectFactory {
     if (typeDefinitionRequiredFields.length > 0) {
       typeDefinition['required'] = typeDefinitionRequiredFields;
     }
-    schemas[type.name] = typeDefinition;
-    return type.name;
+    const customSchema: ApiSchemaOptions[] = Reflect.getOwnMetadata(
+      DECORATORS.API_SCHEMA,
+      type
+    );
+    const schemaName =
+      customSchema && customSchema.length === 1
+        ? customSchema[0].name
+        : type.name;
+    schemas[schemaName] = typeDefinition;
+    return schemaName;
   }
 
   mergePropertyWithMetadata(

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

@@ -1,4 +1,4 @@
-import { ApiProperty } from '../../lib/decorators';
+import { ApiProperty, ApiSchema } 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';
@@ -265,5 +265,33 @@ describe('SchemaObjectFactory', () => {
         properties: { name: { type: 'string', minLength: 1 } }
       });
     });
+
+    it('should use schema name instead of class name', () => {
+      @ApiSchema({
+        name: 'CreateUser'
+      })
+      class CreateUserDto {}
+
+      const schemas = [];
+
+      schemaObjectFactory.exploreModelSchema(CreateUserDto, schemas);
+
+      expect(Object.keys(schemas[0])[0]).toEqual('CreateUser');
+    });
+
+    it('should not use schema name of base class', () => {
+      @ApiSchema({
+        name: 'CreateUser'
+      })
+      class CreateUserDto {}
+
+      class UpdateUserDto extends CreateUserDto {}
+
+      const schemas = [];
+
+      schemaObjectFactory.exploreModelSchema(UpdateUserDto, schemas);
+
+      expect(Object.keys(schemas[0])[0]).toEqual('UpdateUserDto');
+    });
   });
 });