{"skill":{"slug":"swagger-skill","displayName":"swagger-skill","summary":"智能 Swagger API 查询和调用工具。通过自然语言指令直接查询接口详情、调用 API，无需繁琐的交互步骤。","description":"---\nname: swagger-skill\ndescription: 智能 Swagger API 查询和调用工具。通过自然语言指令直接查询接口详情、调用 API，无需繁琐的交互步骤。\nmetadata:\n  clawdbot:\n    emoji: \"🏔️\"\n    requires:\n      bins: [\"node\"]\n---\n\n## 功能特性\n\n- **一键查询**: 直接查询接口详情，自动解析参数、请求体、响应模式\n- **自然语言搜索**: 根据自然语言描述找到匹配的接口（如\"保存用户\"、\"获取数据集列表\"），支持 tags 匹配\n- **智能接口调用**: 根据自然语言指令自动匹配并调用相应的 API\n- **完整信息展示**: 自动获取并展示接口的完整信息（参数、请求体、响应、数据模式定义）\n- **文件上传支持**: 支持 multipart/form-data 文件上传\n- **分层缓存**: 轻量索引用于列表/搜索，Map 结构 O(1) 详情查找\n- **Swagger 2.0 兼容**: 同时支持 OpenAPI 3.0 和 Swagger 2.0 规范\n- **灵活认证**: 支持 Token、Cookie 或无需验证的多种认证方式\n\n## 安装\n\n无需手动安装依赖。首次使用时会自动检测并安装所需依赖（axios、form-data），同时自动初始化 package.json（含 `\"type\": \"module\"` 配置）。\n\n如需手动安装，可在 skill 目录下执行：\n\n```bash\nnpm install\n```\n\n## 使用方法\n\n### 基础使用\n\n```javascript\nimport SwaggerAPISkill from './index.js';\n\nconst skill = new SwaggerAPISkill();\n\n// 1. 加载 Swagger 规范\nawait skill.fetchSwaggerSpec('https://api.example.com/swagger.json');\n\n// 2. 获取所有接口\nconst allAPIs = skill.getAllAPIs();\n\n// 3. 搜索接口\nconst results = skill.searchAPI('获取用户信息');\n\n// 4. 获取接口详情\nconst detail = skill.getAPIDetail('/users/{id}', 'GET');\n\n// 5. 调用接口\nconst response = await skill.callAPI('/users', 'GET', {\n  query: { page: 1, limit: 10 }\n});\n\n// 6. 通过自然语言指令调用\nconst result = await skill.callAPIByInstruction('获取所有用户', {\n  query: { page: 1 }\n});\n```\n\n## 认证方法\n\n### 方法 1: 使用 Token 认证\n\n```javascript\nimport SwaggerAPISkill from './index.js';\n\nconst skill = new SwaggerAPISkill();\n\n// 方式 A: 先设置 Token，再加载规范\nskill.setAuthToken('your-jwt-token');\nawait skill.fetchSwaggerSpec('http://localhost:8090/v2/api-docs');\n\n// 方式 B: 在加载规范时直接传入 Token\nawait skill.fetchSwaggerSpec('http://localhost:8090/v2/api-docs', {\n  token: 'your-jwt-token',\n  tokenOptions: {\n    tokenType: 'Bearer',\n    headerName: 'Authorization'\n  }\n});\n\n// 调用 API（会自动添加认证头）\nconst result = await skill.callAPI('/sysUser/list', 'POST', {\n  body: { pageNum: 1, pageSize: 10 }\n});\n```\n\n### 方法 2: 使用 Cookie 认证\n\n```javascript\nconst skill = new SwaggerAPISkill();\n\n// 方式 A: 先设置 Cookie，再加载规范\nskill.setAuthCookies({\n  token: 'your-token',\n  JSESSIONID: 'your-session-id'\n});\nawait skill.fetchSwaggerSpec('http://localhost:8090/v2/api-docs');\n\n// 方式 B: 在加载规范时直接传入 Cookie\nawait skill.fetchSwaggerSpec('http://localhost:8090/v2/api-docs', {\n  cookies: {\n    token: 'your-token',\n    JSESSIONID: 'your-session-id'\n  }\n});\n```\n\n### 方法 3: 无需认证\n\n```javascript\nconst skill = new SwaggerAPISkill();\n\n// 直接加载规范\nawait skill.fetchSwaggerSpec('http://localhost:8090/v2/api-docs');\n\n// 调用 API\nconst result = await skill.callAPI('/users', 'GET', {\n  query: { page: 1, limit: 10 }\n});\n```\n\n### 方法 4: 使用 CLI 工具（推荐）\n\n```bash\nnode cli.js\n```\n\n交互式 CLI 工具会引导你：\n1. 输入 Swagger API 文档 URL\n2. 输入认证 Token（可选）\n3. 通过菜单选择操作（获取接口列表、搜索、调用等）\n\n## API 文档\n\n### fetchSwaggerSpec(url, options)\n\n获取并加载 Swagger 规范文件。\n\n**参数:**\n- `url` (string): Swagger JSON URL 或 API 基础 URL\n- `options` (object): 可选配置\n  - `token` (string): JWT Token 或其他认证 Token\n  - `cookies` (object): Cookie 对象，如 `{ token: 'xxx', JSESSIONID: 'xxx' }`\n  - `tokenOptions` (object): Token 选项\n    - `tokenType` (string): Token 类型，默认为 'Bearer'\n    - `headerName` (string): 请求头名称，默认为 'Authorization'\n\n**返回:**\n```javascript\n{\n  success: boolean,\n  apiCount?: number,    // 接口总数\n  cached?: boolean,     // 仅缓存命中时返回 true\n  error?: string\n}\n```\n\n### setAuthToken(token, options)\n\n设置认证 Token。\n\n**参数:**\n- `token` (string): JWT Token 或其他认证 Token\n- `options` (object): 可选配置\n  - `tokenType` (string): Token 类型，默认为 'Bearer'\n  - `headerName` (string): 请求头名称，默认为 'Authorization'\n\n**返回:**\n```javascript\n{\n  success: boolean,\n  message: string\n}\n```\n\n### setAuthCookies(cookies)\n\n设置认证 Cookie。\n\n**参数:**\n- `cookies` (object): Cookie 对象，如 `{ token: 'xxx', JSESSIONID: 'xxx' }`\n\n**返回:**\n```javascript\n{\n  success: boolean,\n  message: string\n}\n```\n\n### clearAuth()\n\n清除认证信息。\n\n**返回:**\n```javascript\n{\n  success: boolean,\n  message: string\n}\n```\n\n### getAllAPIs()\n\n获取所有接口的基本信息。\n\n**返回:**\n```javascript\n{\n  success: boolean,\n  total: number,\n  apis: Array<{\n    path: string,\n    method: string,\n    summary: string,\n    description: string,\n    operationId: string,\n    tags: string[]\n  }>\n}\n```\n\n### searchAPI(query)\n\n根据自然语言查询搜索接口。支持 summary、description、path、operationId 和 tags 匹配。\n\n**参数:**\n- `query` (string): 自然语言查询字符串\n\n**返回:**\n```javascript\n{\n  success: boolean,\n  query: string,\n  matchCount: number,\n  results: Array<{\n    path: string,\n    method: string,\n    summary: string,\n    description?: string,  // 仅非空时返回\n    score: number\n  }>\n}\n```\n\n### getAPIDetail(path, method)\n\n获取特定接口的详细信息。使用 Map O(1) 查找。\n\n**参数:**\n- `path` (string): API 路径，如 `/users/{id}`\n- `method` (string): HTTP 方法，如 `GET`, `POST` 等\n\n**返回:**\n```javascript\n{\n  success: boolean,\n  detail?: {\n    path: string,\n    method: string,\n    summary: string,\n    description: string,\n    parameters: Array,\n    requestBody: object,\n    responses: object,\n    tags: Array\n  },\n  error?: string\n}\n```\n\n### getFullAPIDetail(path, method)\n\n获取完整的接口详情，包括关联的数据模式定义。兼容 OpenAPI 3.0 和 Swagger 2.0。\n\n**参数:**\n- `path` (string): API 路径\n- `method` (string): HTTP 方法\n\n**返回:**\n```javascript\n{\n  success: boolean,\n  detail?: {\n    path: string,\n    method: string,\n    summary: string,\n    description: string,\n    parameters: Array,\n    requestBody: object,\n    responses: object,\n    tags: Array,\n    relatedSchemas: object,  // 关联的数据模式定义\n    schemaCount: number\n  },\n  error?: string\n}\n```\n\n### callAPI(path, method, params)\n\n调用 API 接口。支持 JSON 请求和 multipart/form-data 文件上传。\n\n**参数:**\n- `path` (string): API 路径\n- `method` (string): HTTP 方法\n- `params` (object): 请求参数\n  - `query` (object): 查询参数\n  - `body` (object): 请求体（JSON 或 FormData）\n  - `headers` (object): 自定义请求头\n  - `isFormData` (boolean): 是否为 FormData（文件上传）\n\n**返回:**\n```javascript\n{\n  success: boolean,\n  status?: number,\n  data?: any,\n  error?: string\n}\n```\n\n**示例 - JSON 请求:**\n```javascript\nconst response = await skill.callAPI('/api/users', 'POST', {\n  body: { name: 'John', email: 'john@example.com' }\n});\n```\n\n**示例 - 文件上传（使用 FormData）:**\n```javascript\nimport FormData from 'form-data';\nimport fs from 'fs';\n\nconst form = new FormData();\nform.append('file', fs.createReadStream('./data.jsonl'));\nform.append('name', 'My Dataset');\nform.append('type', 'train_data');\n\nconst response = await skill.callAPI('/api/datasets/', 'POST', {\n  body: form,\n  isFormData: true\n});\n```\n\n### callAPIByInstruction(instruction, params)\n\n根据自然语言指令调用 API。\n\n**参数:**\n- `instruction` (string): 自然语言指令\n- `params` (object): 请求参数（同 callAPI）\n\n**返回:**\n```javascript\n{\n  success: boolean,\n  instruction: string,\n  matchedAPI?: {\n    path: string,\n    method: string,\n    summary: string,\n    matchScore: number\n  },\n  result: object,\n  error?: string\n}\n```\n\n### uploadFile(path, formData, query)\n\n文件上传方法，支持 multipart/form-data。\n\n**参数:**\n- `path` (string): API 路径\n- `formData` (object): 表单数据对象\n  - `file`: 文件内容（Buffer）或文件路径（string）\n  - 其他字段: 表单字段（自动转换为字符串）\n- `query` (object): 查询参数（可选）\n\n**返回:**\n```javascript\n{\n  success: boolean,\n  status?: number,\n  data?: any,\n  error?: string\n}\n```\n\n**示例:**\n```javascript\nimport SwaggerAPISkill from './index.js';\n\nconst skill = new SwaggerAPISkill();\nawait skill.fetchSwaggerSpec('http://localhost:8000/openapi.json');\n\n// 方式1: 使用文件路径\nconst result1 = await skill.uploadFile('/api/datasets/', {\n  file: './test_dataset.jsonl',\n  name: 'AI知识问答对',\n  type: 'train_data',\n  description: '人工智能相关的问答对数据集'\n});\n\n// 方式2: 使用 Buffer\nimport fs from 'fs';\nconst fileBuffer = fs.readFileSync('./test_dataset.jsonl');\nconst result2 = await skill.uploadFile('/api/datasets/', {\n  file: fileBuffer,\n  name: 'AI知识问答对',\n  type: 'train_data',\n  description: '人工智能相关的问答对数据集'\n});\n```\n\n### getSessionId()\n\n获取当前会话ID。\n\n**返回:**\n```javascript\nstring // 唯一的会话ID，格式: session_timestamp_randomId\n```\n\n### refreshSession()\n\n刷新会话，清空所有缓存数据。\n\n**返回:**\n```javascript\n{\n  success: boolean,\n  message: string\n}\n```\n\n## 缓存机制\n\nswagger-skill 实现了分层缓存来优化性能和 token 消耗：\n\n1. **轻量索引 (apiIndex)**: 仅存储 path/method/summary/description/operationId/tags，用于 `getAllAPIs()` 和 `searchAPI()`\n2. **详情 Map (apiDetailMap)**: `\"METHOD /path\" → 完整详情`，用于 `getAPIDetail()` 的 O(1) 查找\n3. **首次加载**: 调用 `fetchSwaggerSpec()` 时从远程获取规范并构建两层缓存\n4. **后续查询**: 所有查询操作直接使用内存缓存，无需重新加载\n5. **会话管理**: 调用 `refreshSession()` 可清空缓存\n\n## 支持的 HTTP 方法\n\n- GET\n- POST\n- PUT\n- DELETE\n- PATCH\n- HEAD\n- OPTIONS\n\n## 注意事项\n\n1. 需要网络连接来获取 Swagger 规范和调用 API\n2. 某些 API 可能需要身份验证，可通过 `headers` 参数传递认证信息\n3. 自然语言搜索基于关键词匹配，支持 summary、description、path、operationId 和 tags\n4. 路径参数需要在 `query` 参数中提供\n5. **文件上传**:\n   - 使用 `uploadFile()` 方法是最简单的方式，支持文件路径或 Buffer\n   - 也可以使用 `callAPI()` 方法配合 FormData 对象进行更灵活的控制\n   - 文件上传时不需要手动设置 Content-Type，会自动设置为 multipart/form-data\n6. 同时兼容 OpenAPI 3.0 (`components.schemas`) 和 Swagger 2.0 (`definitions`)\n\n## 许可证\n\nMIT\n","topics":["接口"],"tags":{"latest":"1.0.1"},"stats":{"comments":0,"downloads":1449,"installsAllTime":55,"installsCurrent":0,"stars":1,"versions":2},"createdAt":1770955120177,"updatedAt":1779076877396},"latestVersion":{"version":"1.0.1","createdAt":1770964117306,"changelog":"swagger-skill 1.0.1\n\n- 使用说明优化：无需手动安装依赖（axios、form-data），首次运行会自动检测并安装，自动配置 package.json（含 \"type\": \"module\"）。\n- 安装文档中新增自动初始化和依赖处理说明，提升使用便捷性。\n- 其余功能和接口保持兼容。","license":null},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"minusgod","userId":"s1708fnkzs9q8t7vq376gdg0q5885rp0","displayName":"MinusGod","image":"https://avatars.githubusercontent.com/u/26429639?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779973253387}}