@lark-apaas/nestjs-openapi-devtools

NestJS OpenAPI 开发工具，提供 Swagger 文档生成和客户端 SDK 自动生成功能。

功能特性

• 📚 Swagger 文档生成: 自动生成和挂载 Swagger UI
• 🔄 客户端 SDK 生成: 基于 OpenAPI 规范自动生成 TypeScript/Axios 客户端
• 🎨 自定义客户端: 支持使用自定义 axios 客户端插件
• 📦 双版本支持: 提供 DevToolsModule (v1, deprecated) 和 DevToolsV2Module

安装

npm install @lark-apaas/nestjs-openapi-devtools
# or
yarn add @lark-apaas/nestjs-openapi-devtools

使用方式

DevToolsV2Module (推荐)

使用 @hey-api/openapi-ts 生成现代化的客户端 SDK：

import { DevToolsV2Module } from '@lark-apaas/nestjs-openapi-devtools';

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

  // 挂载 DevTools V2
  await DevToolsV2Module.mount(app, {
    docsPath: 'api-docs',                    // Swagger UI 路径
    openapiOut: 'openapi/openapi.json',      // OpenAPI JSON 输出路径
    clientSdkOut: 'src/sdk',                 // 客户端 SDK 输出路径
    needSetupServer: true,                   // 是否挂载 Swagger UI
    needGenerateClientSdk: true,             // 是否生成客户端 SDK
    swaggerOptions: {
      title: 'API Documentation',
      version: '1.0.0',
      customSiteTitle: 'My API Docs',
    },
  });

  await app.listen(3000);
}

DevToolsModule (已废弃)

使用 openapi-typescript-codegen 生成客户端 SDK（不推荐）：

import { DevToolsModule } from '@lark-apaas/nestjs-openapi-devtools';

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

  await DevToolsModule.mount(app, {
    // ... 相同的配置
  });

  await app.listen(3000);
}

配置选项

interface DevToolsOptions {
  // Swagger UI 挂载路径
  docsPath?: string;                    // 默认: 'api-docs'

  // OpenAPI JSON 文件输出路径
  openapiOut?: string;                  // 默认: 'openapi/openapi.json'

  // 客户端 SDK 输出路径
  clientSdkOut?: string;                // 默认: 'src/sdk'

  // 是否挂载 Swagger UI 服务器
  needSetupServer?: boolean;            // 默认: true

  // 是否生成客户端 SDK
  needGenerateClientSdk?: boolean;      // 默认: true

  // Swagger 配置选项
  swaggerOptions?: {
    title?: string;                     // 默认: 'API Documentation'
    version?: string;                   // 默认: '1.0.0'
    customSiteTitle?: string;           // 默认: 'API Documentation'
    customCss?: string;                 // 自定义 CSS
  };
}

DevToolsV2 vs DevTools

| 特性 | DevToolsV2Module | DevToolsModule (deprecated) | |------|------------------|----------------------------| | SDK 生成器 | @hey-api/openapi-ts | openapi-typescript-codegen | | 类型安全 | ✅ 更好 | ⚠️ 一般 | | 自定义客户端 | ✅ 支持 | ❌ 不支持 | | 维护状态 | ✅ 活跃维护 | ⚠️ 已废弃 | | 推荐使用 | ✅ 是 | ❌ 否 |

错误处理与日志控制

日志文件控制

为了避免随意写入日志文件，本工具对 SDK 生成过程进行了优化：

• DevToolsV2Module:

  • 配置 logs.level: 'error' 只输出错误到控制台
  • 配置 logs.path: undefined 禁用日志文件写入
  • 生成失败时错误信息输出到控制台，不写入文件

• DevToolsModule (deprecated):

  • 生成失败时错误信息输出到控制台
  • 避免了默认的日志文件生成

调试模式

如果需要查看更详细的错误信息，可以设置环境变量：

DEBUG=1 npm run dev

这样会在控制台输出完整的错误堆栈信息，便于调试。

工作原理

1. 生成 OpenAPI 文档: 基于 NestJS 的 @nestjs/swagger 装饰器自动生成 OpenAPI 规范
2. 挂载 Swagger UI: 在指定路径提供交互式 API 文档界面
3. 导出 JSON: 将 OpenAPI 规范导出为 JSON 文件
4. 生成客户端 SDK: 使用 OpenAPI 规范自动生成 TypeScript 客户端代码

依赖项

• @nestjs/common: NestJS 核心
• @nestjs/swagger: Swagger 文档生成
• @hey-api/openapi-ts: 现代化 SDK 生成器 (V2)
• @lark-apaas/hey-api-custom-client-axios: 自定义 axios 客户端插件
• openapi-typescript-codegen: 传统 SDK 生成器 (V1, deprecated)

License

MIT