OpenAPI - Swagger 接入

安装

yarn add @nest/swagger

项目启动后, api 文档默认会在: localhost:port/api 页面

引入

const config = new DocumentBuilder()
  .setTitle("Learn-Project") // 项目标题
  .setDescription("学习用项目 swagger") // 项目描述
  .setVersion("0.1.0") // 版本
  .addTag("Users") // tags
  .addTag("Auth")
  .addTag("blog")
  .addTag("comment")
  .build();

const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup("api", app, document);

具体装饰器

针对 class / handler:

@ApiTags("User") // 接口分类
@Controller("user")
class UserController {
  @ApiOperation({ summary: "api describe" })
  @ApiOkResponse({
    content: {
      // 接口成功返回后的示例
      "Application/json": {
        example: {
          code: 200,
          message: "create new user success",
          data: { id: 123 },
        },
      },
    },
  })
  @Post("create")
  @ApiBody({ type: [CreateUserDto] }) // 显示设置泛型或接口的元数据
  create(@Body() usersDto: CreateUserDto[]) {
    // logic...
  }
}

针对 dto:

api 文档中会自动读取 dto 类

export enum UserRole {
  Admin = "Admin",
  User = "User",
}

// 增加了 ApiProperty 装饰器的属性将会在 api文档中体现
export class CreateUserDto {
  @ApiProperty()
  username: string;

  @ApiProperty()
  password: string;

  // 识别枚举
  @ApiProperty({ enum: ["Admin", "User"] })
  role: UserRole;

  // 手动指明数组类型
  @APiproperty({ type: [String] })
  major: string[];

  // 枚举可以与 @ApiQuery, @Query 装饰器结合使用
  // @ApiQuery({ name: "role", enum: UserRole })
  // filterByRole(@Query("role") role: UserRole = UserRole.User) {}
}

启用 cli 插件

cli 插件将:

• 自动注释 DTO 属性
• 根据问号设置 required 属性
• 根据类型设置 type 或 enum 属性
• 根据分配的默认值设置 default 属性
• 根据 class-validator 装饰器设置几个验证规则
• 根据注释为属性生成示例值
• ...

开启:

// nest-cli.json

{
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "plugins": ["@nestjs/swagger"]
  }
}

自定义插件行为:

{
  "plugins": [
    {
      "name": "@nestjs/swagger",
      "options": {
        "dtoFileNameSuffix": ["dto.ts", ".entity.ts"], // dto 文件后缀
        "controllerFileNameSuffix": ".controller.ts", // 控制器文件后缀
        "classValidatorShim": true, // 如果为 true, 模块将重用 验证装饰器 class-validator
        "dtoKeyOfComment": "description", // 用于在 ApiProperty 上设置注释文本的属性键 for dto
        "controllerKeyOfComment": "description", // 用于在 ApiProperty 上设置注释文本的属性键 for controller
        "introspectComments": true // 如果为 true, 插件将根据注释为属性生成描述值和示例值
        // ...
      }
    }
  ]
}

具体内容见: 链接