npm package: @lark-apaas/nestjs-openapi-devtools
Description: NestJS OpenAPI development tools for Swagger documentation and client SDK generation
Latest version: 1.0.10

# @lark-apaas/nestjs-openapi-devtools

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

## 功能特性

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

## 安装

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

## 使用方式

### DevToolsV2Module (推荐)

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

```typescript
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（不推荐）：

```typescript
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);
}
```

## 配置选项

```typescript
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):
  - 生成失败时错误信息输出到控制台
  - 避免了默认的日志文件生成

### 调试模式

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

```bash
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