新的 NestJS Swagger 生成器比以往更强大

最新推荐文章于 2024-09-08 08:50:58 发布

国资小新

最新推荐文章于 2024-09-08 08:50:58 发布

阅读量56

点赞数

文章标签：前端 javascript 服务器开发语言 ecmascript

新的 NestJS Swagger 生成器

import { NestiaSwaggerComposer } from "@nestia/sdk";
import { INestApplication } from "@nestjs/common";
import { NestFactory } from "@nestjs/core";
import { SwaggerModule } from "@nestjs/swagger";

const main = async (): Promise<void> => {
  const app: INestApplication = await NestFactory.create(ApplicationModule);
  const document = await NestiaSwaggerComposer.document(app, {
    openapi: "3.1",
    servers: [
      {
        url: "http://localhost:3000",
        description: "Localhost"
      }
    ]
  });
  SwaggerModule.setup("api", app, document as any);
  await app.listen(3_000);
};
main().catch(console.error);

OpenAPI (Swagger) 文档生成器在 NestJS 中有了新的进化。

@nestia/sdk 自动分析 NestJS 源代码，在编译级别生成 OpenAPI 文档，无需像 @nestjs/swagger 装饰器函数调用那样额外操作。所有过程都由 @nestia/sdk 自动完成。

让我们设置 @nestia/sdk，并利用它的优势吧。

Github 仓库: https://github.com/samchon/nestia
使用文档: https://nestia.io/docs/sdk/swagger/#runtime-composition

DTO Schema

//----
// 在 @nestia/sdk 中仅需使用接口类型
//----
export interface IBbsArticle {
  /**
   * 附件文件列表。
   */
  files: null | IAttachmentFile[];
}

//----
// 在 @nestjs/swagger 中需要重复定义
//----
export class BbsArticle {
  // 重复的模式定义
  // - 重复的函数调用 + 属性类型
  // - 必须自己指定 `isArray` 和 `nullable` 属性
  @ApiProperty({
    type: () => AttachmentFile,
    nullable: true,
    isArray: true,
    description: "附加文件列表。",
  })
  @Type(() => AttachmentFile)
  @IsArray()
  @IsOptional()
  @IsObject({ each: true })
  @ValidateNested({ each: true })
  files: null | AttachmentFile[];
}

请看下面的 DTO（数据传输对象）模式示例，分别用于 @nestia/sdk 和 @nestjs/swagger。哪一种更方便？如你所见，@nestia/sdk 只需纯 TypeScript 类型。而 @nestjs/swagger 需要在 DTO 模式中进行三重重复的类型定义。

考虑到安全性，@nestia/sdk 更加有用。由于 @nestjs/swagger 在 DTO 模式中的三重重复定义，生产力和可维护性降低，容易导致用户犯错。更糟糕的是，如果你错误使用了 @nestjs/swagger 装饰器，即使它们与实际的 TypeScript 类型不同，也不会出现编译错误。此外，@nestia/sdk 只需要纯 TypeScript 类型，因此不会出现类似 @nestjs/swagger 的问题。

这就是你应该在 NestJS 中使用 @nestia/sdk 进行 OpenAPI 生成的原因。@nestia/sdk 将分析你的 TypeScript DTO 类型，在编译级别自动生成 OpenAPI 规范的 JSON 模式。使用它可以同时提升生产力、可维护性和安全性。