jszy-swagger-doc-generator 1.1.0

package/OpenAPI.md

@@ -0,0 +1,298 @@
+## 1. 后端 OpenAPI 文档要求
+
+为了能够正确生成前端 SDK，后端需要提供符合特定格式的 OpenAPI 3.1 规范文档。以下是具体要求：
+
+### 1.1 OpenAPI 文档结构要求
+
+后端 API 文档必须遵循 OpenAPI 3.1 规范，并包含以下必要组成部分：
+
+#### 1.1.1 文档根结构
+```json
+{
+  "openapi": "3.1.0-rc0",
+  "info": {
+    "title": "服务名称",
+    "description": "服务描述",
+    "version": "API 版本"
+  },
+  "servers": [
+    {
+      "url": "服务地址",
+      "description": "环境描述",
+      "x-environment": "环境标识"
+    }
+  ],
+  "components": {
+    "schemas": {
+      // 数据模型定义
+    }
+  },
+  "paths": {
+    // API 端点定义
+  }
+}
+```
+
+#### 1.1.2 数据模型定义 (components.schemas)
+
+数据模型必须按照以下格式定义：
+
+1. **对象类型**：
+```json
+"ModelName": {
+  "type": "object",
+  "properties": {
+    "field_name": {
+      "type": "数据类型",  // string, integer, number, boolean, array 等
+      "format": "格式说明",  // 如 timestamp, date 等
+      "pattern": "正则表达式", // 如 "^\\d{4}-\\d{2}-\\d{2}$"
+      "title": "字段标题"  // 作为 TypeScript 注释
+    }
+  },
+  "required": ["必需字段列表"]
+}
+```
+
+2. **枚举类型**：
+```json
+"EnumName": {
+  "type": "string",
+  "enum": ["值1", "值2", "值3"]
+}
+```
+
+3. **联合类型 (oneOf)**：
+```json
+"UnionType": {
+  "oneOf": [
+    {
+      "type": "null"
+    },
+    {
+      "$ref": "#/components/schemas/OtherModel"
+    }
+  ]
+}
+```
+
+4. **数组类型**：
+```json
+"ArrayField": {
+  "type": "array",
+  "items": {
+    "$ref": "#/components/schemas/ItemType"
+  }
+}
+```
+
+5. **可空类型处理**：
+- 使用数组形式 `"type": ["string", "null"]`
+- 或使用 `oneOf` 包含 null 类型
+
+#### 1.1.3 API 端点定义 (paths)
+
+API 端点必须按照以下格式定义：
+
+1. **路径和操作**：
+```json
+"/api/path/{paramName}": {
+  "get|post|put|delete": {
+    "summary": "API 摘要",  // 作为 TypeScript 注释
+    "description": "API 描述",  // 作为 TypeScript 注释
+    "tags": ["分组名称"],  // 用于 API 分组
+    "operationId": "apiMethodName",  // 生成的 API 方法名
+    "parameters": [...],  // 请求参数
+    "requestBody": {...},  // 请求体 (POST/PUT)
+    "responses": {...}    // 响应定义
+  }
+}
+```
+
+2. **参数定义**：
+```json
+"parameters": [
+  {
+    "name": "参数名",
+    "in": "path|query|header|cookie",  // 参数位置
+    "schema": {
+      "type": "参数类型",
+      "format": "格式"
+    },
+    "required": true|false,  // 是否必需
+    "description": "参数描述"
+  }
+]
+```
+
+3. **请求体定义**：
+```json
+"requestBody": {
+  "description": "请求体描述",
+  "content": {
+    "application/json": {
+      "schema": {
+        "$ref": "#/components/schemas/RequestBodyModel"
+      }
+    }
+  },
+  "required": true
+}
+```
+
+4. **响应定义**：
+```json
+"responses": {
+  "200": {
+    "description": "成功响应描述",
+    "content": {
+      "application/json": {
+        "schema": {
+          "$ref": "#/components/schemas/ResponseModel"
+        }
+      }
+    }
+  },
+  "201": {
+    // 创建成功响应
+  },
+  "204": {
+    "description": "No Content"  // 无返回值
+  },
+  "500": {
+    // 错误响应
+  }
+}
+```
+
+### 1.2 特殊类型处理
+
+#### 1.2.1 引用处理
+- 使用 `$ref` 引用定义在 `components.schemas` 中的模型
+- 格式：`"$ref": "#/components/schemas/ModelName"`
+
+#### 1.2.2 类型映射
+- `integer` → TypeScript `number`
+- `string` → TypeScript `string`
+- `boolean` → TypeScript `boolean`
+- `array` → TypeScript `Type[]`
+- `null` → TypeScript 可空类型
+
+#### 1.2.3 字段特性
+- 使用 `title` 属性作为字段注释
+- 使用 `description` 属性作为详细说明
+- 使用 `pattern` 属性定义字符串格式验证
+
+### 1.3 生成器特殊处理
+
+当前 SDK 生成器会进行以下特殊处理：
+
+1. **路径参数转换**：将路径中的 `{paramName}` 转换为 `{paramName}` 并进行驼峰命名
+2. **参数展开**：对于可选参数，会将对象参数展开为多个独立参数
+3. **默认值处理**：为可空字段生成适当的默认值处理逻辑
+4. **导入检测**：自动分析类型依赖关系并生成相应的导入语句
+
+### 1.4 完整示例
+
+以下是一个完整的 API 端点定义示例：
+
+```json
+{
+  "openapi": "3.1.0-rc0",
+  "info": {
+    "title": "Example Service",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/users/{userId}": {
+      "get": {
+        "summary": "获取用户信息",
+        "description": "根据用户ID获取用户详细信息",
+        "tags": ["User"],
+        "operationId": "getUserById",
+        "parameters": [
+          {
+            "name": "userId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "integer"
+            },
+            "description": "用户ID"
+          },
+          {
+            "name": "includeProfile",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "boolean",
+              "default": false
+            },
+            "description": "是否包含用户档案信息"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "成功获取用户信息",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/User"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "User": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "integer",
+            "title": "用户ID"
+          },
+          "name": {
+            "type": "string",
+            "title": "用户名"
+          },
+          "email": {
+            "type": ["string", "null"],
+            "title": "邮箱地址"
+          },
+          "profile": {
+            "oneOf": [
+              {
+                "type": "null"
+              },
+              {
+                "$ref": "#/components/schemas/UserProfile"
+              }
+            ],
+            "title": "用户档案"
+          }
+        },
+        "required": ["id", "name"]
+      },
+      "UserProfile": {
+        "type": "object",
+        "properties": {
+          "age": {
+            "type": "integer",
+            "title": "年龄"
+          },
+          "bio": {
+            "type": "string",
+            "title": "个人简介"
+          }
+        },
+        "required": ["age", "bio"]
+      }
+    }
+  }
+}
+```
+
+这个自动化 SDK 生成系统通过解析 OpenAPI 规范，使用模板引擎生成类型安全的 TypeScript 代码，大大减少了手动编写 API 客户端的工作量，同时确保了前端与后端 API 的一致性。

package/README.md

@@ -0,0 +1,193 @@
+# Swagger Documentation Generator
+
+A tool to generate frontend documentation, TypeScript types, and React Hooks from Swagger/OpenAPI JSON files.
+
+## Installation
+
+You can install this package globally to use it as a CLI tool:
+
+```bash
+npm install -g swagger-doc-generator
+```
+
+Or you can use it without installing with npx:
+
+```bash
+npx swagger-doc-generator
+```
+
+## Usage
+
+### Command Line Interface
+
+The tool can be used from the command line to generate documentation, TypeScript types, or React Hooks from a Swagger JSON file:
+
+#### Generate Documentation (Default)
+```bash
+# Generate documentation from a URL (output to ./generated/docs/api-documentation.md by default)
+swagger-doc-generator --url https://petstore.swagger.io/v2/swagger.json
+
+# Generate documentation from a local file (output to ./generated/docs/api-documentation.md by default)
+swagger-doc-generator --input ./swagger.json
+
+# Generate documentation and specify output file
+swagger-doc-generator --url https://petstore.swagger.io/v2/swagger.json --output ./docs/api-documentation.md
+```
+
+#### Generate TypeScript Types
+```bash
+# Generate TypeScript types from a local file (output to ./generated/types/ by default)
+swagger-doc-generator --input ./swagger.json --generate-types
+
+# Generate TypeScript types with custom output directory
+swagger-doc-generator --input ./swagger.json --generate-types --types-output ./src/types
+```
+
+#### Generate React Hooks
+```bash
+# Generate React hooks from a local file (output to ./generated/hooks/ by default)
+swagger-doc-generator --input ./swagger.json --generate-hooks
+
+# Generate React hooks with custom output directory
+swagger-doc-generator --input ./swagger.json --generate-hooks --hooks-output ./src/hooks
+
+# Generate both types and hooks (output to ./generated/ directories by default)
+swagger-doc-generator --input ./swagger.json --generate-types --generate-hooks
+```
+
+#### Default Output Location
+By default, all generated content is placed in the `./generated` directory to keep your project clean and separate generated content from source code:
+
+- Documentation: `./generated/docs/api-documentation.md`
+- TypeScript types: `./generated/types/`
+- React hooks: `./generated/hooks/`
+
+### Programmatic Usage
+
+You can also use this package programmatically in your JavaScript/TypeScript code:
+
+```javascript
+const { SwaggerDocGenerator } = require('swagger-doc-generator');
+
+async function generate() {
+  const generator = new SwaggerDocGenerator();
+
+  // Load from URL
+  const swaggerDoc = await generator.fetchSwaggerJSON('https://api.example.com/swagger.json');
+
+  // Or load from file
+  // const swaggerDoc = generator.loadSwaggerFromFile('./swagger.json');
+
+  // Generate documentation
+  const documentation = generator.generateDocumentation(swaggerDoc);
+  generator.saveDocumentationToFile(documentation, './docs/api-documentation.md');
+
+  // Generate TypeScript types
+  const types = generator.generateTypeDefinitions(swaggerDoc);
+  generator.saveTypesToFile(types, './types/api-types.ts');
+
+  // Generate React hooks organized by tags
+  const hooksByTag = generator.generateReactHooks(swaggerDoc);
+  generator.saveHooksByTag(hooksByTag, './hooks');
+}
+
+generate().catch(console.error);
+```
+
+## Options
+
+- `--url, -u`: URL to the Swagger JSON file
+- `--input, -i`: Path to the local Swagger JSON file
+- `--output, -o`: Output path for the generated documentation (default: ./docs/api-documentation.md)
+- `--generate-types`: Generate TypeScript type definitions
+- `--generate-hooks`: Generate React hooks
+- `--types-output`: Output directory for TypeScript types (default: ./types)
+- `--hooks-output`: Output directory for React hooks (default: ./hooks)
+- `--help`: Show help information
+
+## Features
+
+- Fetches Swagger JSON from a URL
+- Loads Swagger JSON from a local file
+- Generates comprehensive documentation in Markdown format
+- Generates TypeScript type definitions from schemas
+- Generates React Hooks for API endpoints, organized by tags
+- Supports both Swagger 2.0 and OpenAPI 3.x specifications
+- Handles API endpoints, parameters, request/response bodies, and responses
+- Creates output directory if it doesn't exist
+- Properly handles path and query parameters
+- Generates proper TypeScript interfaces and type aliases
+- Organizes generated code by API tags
+
+## Example Output
+
+### Generated TypeScript Types
+```typescript
+// Auto-generated TypeScript types from Swagger schema
+
+export interface User {
+  /** 用户ID */
+  id: number;
+  /** 用户名 */
+  name: string;
+  /** 用户邮箱 */
+  email: string;
+  /** 头像URL */
+  avatar?: string;
+}
+
+export interface UserConfig {
+  /** 用户ID */
+  userId: number;
+  /** 主题设置 */
+  theme: "light" | "dark";
+  /** 语言设置 */
+  language: string;
+  /** 通知设置 */
+  notifications: NotificationSettings;
+  /** 个性化设置 */
+  preferences: Preferences;
+}
+```
+
+### Generated React Hooks
+```typescript
+// Users API Hooks
+
+export interface UserController_queryUserInfoParams {
+  id?: number;
+  name?: string;
+}
+
+export const useUserController_queryUserInfo = () => {
+  const apiCall = async (params: UserController_queryUserInfoParams) => {
+    const path = `${process.env.REACT_APP_API_BASE_URL || ''}/api/queryUserInfo`;
+    const queryParams = new URLSearchParams();
+    if (params.id) queryParams.append('id', params.id.toString());
+    if (params.name) queryParams.append('name', params.name.toString());
+    const queryString = queryParams.toString();
+    const url = `${path}${queryString ? '?' + queryString : ''}`;
+    const options: RequestInit = {
+      method: 'GET',
+    };
+
+    const result = await fetch(url, options);
+    return result.json() as Promise<User[]>;
+  };
+
+  return { userController_queryUserInfo: apiCall };
+};
+```
+
+## Development
+
+To run this project locally:
+
+1. Clone the repository
+2. Run `pnpm install` to install dependencies
+3. Run `pnpm run build` to compile TypeScript
+4. Run `pnpm run test` to run tests
+
+## License
+
+MIT

package/__tests__/index.test.ts

@@ -0,0 +1,152 @@
+import { SwaggerDocGenerator, SwaggerDoc } from '../src/index';
+import axios from 'axios';
+import * as fs from 'fs';
+
+// Mock swagger doc for testing
+const mockSwaggerDoc: SwaggerDoc = {
+  swagger: "2.0",
+  info: {
+    title: "Test API",
+    version: "1.0.0",
+    description: "A test API"
+  },
+  paths: {
+    "/test": {
+      get: {
+        summary: "Get test",
+        description: "Returns test data",
+        responses: {
+          "200": {
+            description: "Successful response",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    message: {
+                      type: "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+};
+
+// Create a mock for the fs module
+jest.mock('fs');
+
+describe('SwaggerDocGenerator', () => {
+  let generator: SwaggerDocGenerator;
+
+  beforeEach(() => {
+    generator = new SwaggerDocGenerator();
+    // Reset all mocks before each test
+    jest.clearAllMocks();
+  });
+
+  describe('fetchSwaggerJSON', () => {
+    it('should fetch swagger JSON from a URL', async () => {
+      const mockUrl = 'https://api.example.com/swagger.json';
+
+      // Mock the axios response
+      jest.spyOn(axios, 'get').mockResolvedValueOnce({ data: mockSwaggerDoc });
+
+      const result = await generator.fetchSwaggerJSON(mockUrl);
+
+      expect(result).toEqual(mockSwaggerDoc);
+      expect(axios.get).toHaveBeenCalledWith(mockUrl);
+    });
+
+    it('should handle errors when fetching swagger JSON', async () => {
+      const mockUrl = 'https://api.example.com/invalid.json';
+
+      // Mock the axios response to reject
+      jest.spyOn(axios, 'get').mockRejectedValueOnce(new Error('Network error'));
+
+      await expect(generator.fetchSwaggerJSON(mockUrl)).rejects.toThrow(
+        `Failed to fetch Swagger JSON from ${mockUrl}: Network error`
+      );
+    });
+  });
+
+  describe('loadSwaggerFromFile', () => {
+    it('should load swagger JSON from a local file', () => {
+      const mockFilePath = 'test-swagger.json';
+
+      // Mock the file system
+      (fs.readFileSync as jest.Mock).mockReturnValue(JSON.stringify(mockSwaggerDoc));
+
+      const result = generator.loadSwaggerFromFile(mockFilePath);
+
+      expect(result).toEqual(mockSwaggerDoc);
+      expect(fs.readFileSync).toHaveBeenCalledWith(mockFilePath, 'utf8');
+    });
+
+    it('should handle errors when loading swagger JSON from file', () => {
+      const mockFilePath = 'nonexistent.json';
+
+      // Mock the file system to throw an error
+      (fs.readFileSync as jest.Mock).mockImplementation(() => {
+        throw new Error('File not found');
+      });
+
+      expect(() => generator.loadSwaggerFromFile(mockFilePath)).toThrow(
+        `Failed to load Swagger JSON from ${mockFilePath}: File not found`
+      );
+    });
+  });
+
+  describe('generateDocumentation', () => {
+    it('should generate documentation from swagger doc', () => {
+      const result = generator.generateDocumentation(mockSwaggerDoc);
+
+      expect(result).toContain('# Test API');
+      expect(result).toContain('A test API v1.0.0');
+      expect(result).toContain('## API Endpoints');
+      expect(result).toContain('### GET /test');
+      expect(result).toContain('**Summary:** Get test');
+      expect(result).toContain('**Description:** Returns test data');
+      expect(result).toContain('**Responses:**');
+      expect(result).toContain('- **200**: Successful response');
+    });
+  });
+
+  describe('saveDocumentationToFile', () => {
+    it('should save documentation to a file', () => {
+      const mockDocumentation = '# Test Documentation';
+      const mockOutputPath = './docs/test.md';
+
+      // Mock the file system methods
+      (fs.existsSync as jest.Mock).mockReturnValue(true);
+      (fs.writeFileSync as jest.Mock).mockImplementation();
+      (fs.mkdirSync as jest.Mock).mockImplementation();
+
+      generator.saveDocumentationToFile(mockDocumentation, mockOutputPath);
+
+      expect(fs.existsSync).toHaveBeenCalledWith('./docs');
+      expect(fs.writeFileSync).toHaveBeenCalledWith(mockOutputPath, mockDocumentation, 'utf8');
+      expect(fs.mkdirSync).not.toHaveBeenCalled(); // Because directory exists
+    });
+
+    it('should create directory if it does not exist', () => {
+      const mockDocumentation = '# Test Documentation';
+      const mockOutputPath = './newdir/test.md';
+
+      // Mock the file system methods
+      (fs.existsSync as jest.Mock).mockReturnValue(false);
+      (fs.writeFileSync as jest.Mock).mockImplementation();
+      (fs.mkdirSync as jest.Mock).mockImplementation();
+
+      generator.saveDocumentationToFile(mockDocumentation, mockOutputPath);
+
+      expect(fs.existsSync).toHaveBeenCalledWith('./newdir');
+      expect(fs.mkdirSync).toHaveBeenCalledWith('./newdir', { recursive: true });
+      expect(fs.writeFileSync).toHaveBeenCalledWith(mockOutputPath, mockDocumentation, 'utf8');
+    });
+  });
+});

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};