如何使用Swagger文档化NestJS可复用枚举（展示枚举本身）

针对你要把枚举本身展示在Swagger Schemas部分的需求，以下是两种可行的简便方案：

方案一：手动注册枚举到Swagger文档 #

这种方法可以直接让枚举独立出现在Schemas里，无需额外包装类：

1. 给枚举添加Swagger元数据装饰器
   用@Schema装饰器标记枚举，补充描述信息：

import { Schema } from '@nestjs/swagger';

@Schema({
  description: '扫描状态枚举，对应扫描流程中的各个阶段',
})
export enum ScanState {
  SCAN_WAITING_FOR_CAPTURE_DATA = 'SCAN_WAITING_FOR_CAPTURE_DATA',
  SCAN_VALIDATING_CAPTURE_DATA = 'SCAN_VALIDATING_CAPTURE_DATA',
  SCAN_CAPTURE_DATA_VALID = 'SCAN_CAPTURE_DATA_VALID',
  SCAN_CAPTURE_DATA_INVALID = 'SCAN_CAPTURE_DATA_INVALID',
}

2. 在Swagger初始化时注册枚举
   在main.ts中，通过extraModels把枚举加入文档，并手动补充Schema定义：

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder, ApiExtraModels } from '@nestjs/swagger';
import { AppModule } from './app.module';
import { ScanState } from './path-to-enum/scan-state.enum';

@ApiExtraModels(ScanState)
async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('你的API文档')
    .setDescription('API功能描述')
    .setVersion('1.0')
    .build();

  const document = SwaggerModule.createDocument(app, config, {
    extraModels: [ScanState],
  });

  // 手动配置枚举的Schema，确保正确展示
  document.components.schemas['ScanState'] = {
    type: 'string',
    enum: Object.values(ScanState),
    description: '扫描状态枚举，对应扫描流程中的各个阶段',
  };

  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}
bootstrap();

方案二：用包装类间接实现（更简洁） #

如果不想手动修改文档结构，可以创建一个空的DTO类来引用枚举，让Swagger自动识别并生成枚举Schema：

1. 创建枚举对应的DTO类

import { ApiProperty, ApiExtraModels } from '@nestjs/swagger';
import { ScanState } from './scan-state.enum';

@ApiExtraModels(ScanStateDto)
export class ScanStateDto {
  @ApiProperty({
    enum: ScanState,
    description: '扫描状态枚举，对应扫描流程中的各个阶段',
  })
  state: ScanState;
}

2. 在Swagger初始化时加入该DTO
   在main.ts的createDocument配置中，把ScanStateDto加入extraModels：

const document = SwaggerModule.createDocument(app, config, {
  extraModels: [ScanStateDto],
});

这种方式会同时生成ScanStateDto和ScanState的Schema，但能快速实现枚举的文档化。

内容的提问来源于stack exchange，提问作者brinxi11