通用部分

opss 在做类型推断时，会根据框架的内部实现，抓取每个 controller、service 的入参、返回值，最终生成 openapi，而在这个过程中产生了一些使用 opss 时的开发约定。

生成规范

如果返回值中包含 enum、interface，哪怕是数据深层包含 enum、interface，opss 都会自动识别并生成对应的类型定义。意味着你的请求参数、返回参数中，如果包含 enum、interface，那么你将会在 api 文档中获得实体类型，大概张这样：

更多命名规范

为什么 interface、enum 会被识别，而 type 不会？

因为 type 是泛指为用于计算的类型，或者无名称类型。
如果任何类型都建立实体则可能导致实体命名冲突。

服务命名

@summary 是针对于 controller、service、method 的命名，用于生成文档的标题，如果没有命名则采用 method + url 作为标题。

@tags 是表示 service、method 的目录深度，用于生成文档的目录，nestjs 的 method 可以直接从 controller 的 @tags 继承。

更多命名规范

/**
 * @tags 梦想家/小伙伴
 *
 * @summary 旺财管理
 */
@Controller('dog')
export class DogController {
  constructor(private readonly dogService: DogService) {}
 
  /**
   * @summary 添加一只旺财
   */
  @Post()
  create(@Body() createDogDto: CreateDogDto) {
    return this.dogService.create(createDogDto);
  }
}

返回值

code: 200 as const，返回的 code 或者 status 的返回值被定义为常量就是用来区分接口用例的，在用例中分别有 200、500 两个 code 的用例。如果返回中有 2 个相同的状态值，比如有 2 个 200，则可以通过对返回值 define 一个名称，来区分用例。

@Post('upload')
@UseInterceptors(FileInterceptor('file'))
async uploadFile(@UploadedFile() file: Express.Multer.File) {
  try {
    const uploadResult = await this.appService.uploadFile(file)
    return {
      success: true as const,
      code: 200 as const,
      message: 'File uploaded successfully',
      data: uploadResult,
    }
  }
  catch (error) {
    return {
      success: false as const,
      code: 500 as const,
      message: 'Failed to upload file',
      error: error.message,
    }
  }
}

配置用例 nestjs