首页 专区 Skill 文章 专题 AI工具 学习 编程手册

PHP MySQL jquery HTML CSS
首页 > Skill > AI Agent

swagger-skill

Polar Sponsor
爱发电 赞助
.NET 9.0
立即下载

智能 Swagger API 查询与调用工具，支持自然语言指令直接查询接口详情和调用 API，省去繁琐交互。

一键查询 : 直接查询接口详情，自动解析参数、请求体、响应模式

功能概述

一键查询 : 直接查询接口详情，自动解析参数、请求体、响应模式是一项面向实际任务的技能，主要用于自然语言搜索 : 根据自然语言描述找到匹配的接口（如"保存用户"、"获取数据集列表"），支持 tags 匹配；智能接口调用 : 根据自然语言指令自动匹配并调用相应的 API；

核心要点

  • 完整信息展示 : 自动获取并展示接口的完整信息（参数、请求体、响应、数据模式定义）；
  • 文件上传支持 : 支持 multipart/form-da。
  • 它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。

使用与执行

从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；

结果检查与注意事项

若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。

功能特性

  • 一键查询: 直接查询接口详情，自动解析参数、请求体、响应模式
  • 自然语言搜索: 根据自然语言描述找到匹配的接口（如"保存用户"、"获取数据集列表"），支持 tags 匹配
  • 智能接口调用: 根据自然语言指令自动匹配并调用相应的 API
  • 完整信息展示: 自动获取并展示接口的完整信息（参数、请求体、响应、数据模式定义）
  • 文件上传支持: 支持 multipart/form-data 文件上传
  • 分层缓存: 轻量索引用于列表/搜索，Map 结构 O(1) 详情查找
  • Swagger 2.0 兼容: 同时支持 OpenAPI 3.0 和 Swagger 2.0 规范
  • 灵活认证: 支持 Token、Cookie 或无需验证的多种认证方式

安装

无需手动安装依赖。首次使用时会自动检测并安装所需依赖（axios、form-data），同时自动初始化 package.json（含 "type": "module" 配置）。

如需手动安装，可在 skill 目录下执行：

npm install

使用方法

基础使用

import SwaggerAPISkill from './index.js';

const skill = new SwaggerAPISkill();

// 1. 加载 Swagger 规范
await skill.fetchSwaggerSpec('https://api.example.com/swagger.json');

// 2. 获取所有接口
const allAPIs = skill.getAllAPIs();

// 3. 搜索接口
const results = skill.searchAPI('获取用户信息');

// 4. 获取接口详情
const detail = skill.getAPIDetail('/users/{id}', 'GET');

// 5. 调用接口
const response = await skill.callAPI('/users', 'GET', {
  query: { page: 1, limit: 10 }
});

// 6. 通过自然语言指令调用
const result = await skill.callAPIByInstruction('获取所有用户', {
  query: { page: 1 }
});

认证方法

方法 1: 使用 Token 认证

import SwaggerAPISkill from './index.js';

const skill = new SwaggerAPISkill();

// 方式 A: 先设置 Token，再加载规范
skill.setAuthToken('your-jwt-token');
await skill.fetchSwaggerSpec('http://localhost:8090/v2/api-docs');

// 方式 B: 在加载规范时直接传入 Token
await skill.fetchSwaggerSpec('http://localhost:8090/v2/api-docs', {
  token: 'your-jwt-token',
  tokenOptions: {
    tokenType: 'Bearer',
    headerName: 'Authorization'
  }
});

// 调用 API（会自动添加认证头）
const result = await skill.callAPI('/sysUser/list', 'POST', {
  body: { pageNum: 1, pageSize: 10 }
});

方法 2: 使用 Cookie 认证

const skill = new SwaggerAPISkill();

// 方式 A: 先设置 Cookie，再加载规范
skill.setAuthCookies({
  token: 'your-token',
  JSESSIONID: 'your-session-id'
});
await skill.fetchSwaggerSpec('http://localhost:8090/v2/api-docs');

// 方式 B: 在加载规范时直接传入 Cookie
await skill.fetchSwaggerSpec('http://localhost:8090/v2/api-docs', {
  cookies: {
    token: 'your-token',
    JSESSIONID: 'your-session-id'
  }
});

方法 3: 无需认证

const skill = new SwaggerAPISkill();

// 直接加载规范
await skill.fetchSwaggerSpec('http://localhost:8090/v2/api-docs');

// 调用 API
const result = await skill.callAPI('/users', 'GET', {
  query: { page: 1, limit: 10 }
});

方法 4: 使用 CLI 工具（推荐）

node cli.js

交互式 CLI 工具会引导你：

  1. 输入 Swagger API 文档 URL
  2. 输入认证 Token（可选）
  3. 通过菜单选择操作（获取接口列表、搜索、调用等）

API 文档

fetchSwaggerSpec(url, options)

获取并加载 Swagger 规范文件。

参数:

  • url (string): Swagger JSON URL 或 API 基础 URL
  • options (object): 可选配置
    • token (string): JWT Token 或其他认证 Token
    • cookies (object): Cookie 对象，如 { token: 'xxx', JSESSIONID: 'xxx' }
    • tokenOptions (object): Token 选项
      • tokenType (string): Token 类型，默认为 'Bearer'
      • headerName (string): 请求头名称，默认为 'Authorization'

返回:

{
  success: boolean,
  apiCount?: number,    // 接口总数
  cached?: boolean,     // 仅缓存命中时返回 true
  error?: string
}

setAuthToken(token, options)

设置认证 Token。

参数:

  • token (string): JWT Token 或其他认证 Token
  • options (object): 可选配置
    • tokenType (string): Token 类型，默认为 'Bearer'
    • headerName (string): 请求头名称，默认为 'Authorization'

返回:

{
  success: boolean,
  message: string
}

setAuthCookies(cookies)

设置认证 Cookie。

参数:

  • cookies (object): Cookie 对象，如 { token: 'xxx', JSESSIONID: 'xxx' }

返回:

{
  success: boolean,
  message: string
}

clearAuth()

清除认证信息。

返回:

{
  success: boolean,
  message: string
}

getAllAPIs()

获取所有接口的基本信息。

返回:

{
  success: boolean,
  total: number,
  apis: Array<{
    path: string,
    method: string,
    summary: string,
    description: string,
    operationId: string,
    tags: string[]
  }>
}

searchAPI(query)

根据自然语言查询搜索接口。支持 summary、description、path、operationId 和 tags 匹配。

参数:

  • query (string): 自然语言查询字符串

返回:

{
  success: boolean,
  query: string,
  matchCount: number,
  results: Array<{
    path: string,
    method: string,
    summary: string,
    description?: string,  // 仅非空时返回
    score: number
  }>
}

getAPIDetail(path, method)

获取特定接口的详细信息。使用 Map O(1) 查找。

参数:

  • path (string): API 路径，如 /users/{id}
  • method (string): HTTP 方法，如 GET, POST 等

返回:

{
  success: boolean,
  detail?: {
    path: string,
    method: string,
    summary: string,
    description: string,
    parameters: Array,
    requestBody: object,
    responses: object,
    tags: Array
  },
  error?: string
}

getFullAPIDetail(path, method)

获取完整的接口详情，包括关联的数据模式定义。兼容 OpenAPI 3.0 和 Swagger 2.0。

参数:

  • path (string): API 路径
  • method (string): HTTP 方法

返回:

{
  success: boolean,
  detail?: {
    path: string,
    method: string,
    summary: string,
    description: string,
    parameters: Array,
    requestBody: object,
    responses: object,
    tags: Array,
    relatedSchemas: object,  // 关联的数据模式定义
    schemaCount: number
  },
  error?: string
}

callAPI(path, method, params)

调用 API 接口。支持 JSON 请求和 multipart/form-data 文件上传。

参数:

  • path (string): API 路径
  • method (string): HTTP 方法
  • params (object): 请求参数
    • query (object): 查询参数
    • body (object): 请求体（JSON 或 FormData）
    • headers (object): 自定义请求头
    • isFormData (boolean): 是否为 FormData（文件上传）

返回:

{
  success: boolean,
  status?: number,
  data?: any,
  error?: string
}

示例 - JSON 请求:

const response = await skill.callAPI('/api/users', 'POST', {
  body: { name: 'John', email: 'john@example.com' }
});

示例 - 文件上传（使用 FormData）:

import FormData from 'form-data';
import fs from 'fs';

const form = new FormData();
form.append('file', fs.createReadStream('./data.jsonl'));
form.append('name', 'My Dataset');
form.append('type', 'train_data');

const response = await skill.callAPI('/api/datasets/', 'POST', {
  body: form,
  isFormData: true
});

callAPIByInstruction(instruction, params)

根据自然语言指令调用 API。

参数:

  • instruction (string): 自然语言指令
  • params (object): 请求参数（同 callAPI）

返回:

{
  success: boolean,
  instruction: string,
  matchedAPI?: {
    path: string,
    method: string,
    summary: string,
    matchScore: number
  },
  result: object,
  error?: string
}

uploadFile(path, formData, query)

文件上传方法，支持 multipart/form-data。

参数:

  • path (string): API 路径
  • formData (object): 表单数据对象
    • file: 文件内容（Buffer）或文件路径（string）
    • 其他字段: 表单字段（自动转换为字符串）
  • query (object): 查询参数（可选）

返回:

{
  success: boolean,
  status?: number,
  data?: any,
  error?: string
}

示例:

import SwaggerAPISkill from './index.js';

const skill = new SwaggerAPISkill();
await skill.fetchSwaggerSpec('http://localhost:8000/openapi.json');

// 方式1: 使用文件路径
const result1 = await skill.uploadFile('/api/datasets/', {
  file: './test_dataset.jsonl',
  name: 'AI知识问答对',
  type: 'train_data',
  description: '人工智能相关的问答对数据集'
});

// 方式2: 使用 Buffer
import fs from 'fs';
const fileBuffer = fs.readFileSync('./test_dataset.jsonl');
const result2 = await skill.uploadFile('/api/datasets/', {
  file: fileBuffer,
  name: 'AI知识问答对',
  type: 'train_data',
  description: '人工智能相关的问答对数据集'
});

getSessionId()

获取当前会话ID。

返回:

string // 唯一的会话ID，格式: session_timestamp_randomId

refreshSession()

刷新会话，清空所有缓存数据。

返回:

{
  success: boolean,
  message: string
}

缓存机制

swagger-skill 实现了分层缓存来优化性能和 token 消耗：

  1. 轻量索引 (apiIndex): 仅存储 path/method/summary/description/operationId/tags，用于 getAllAPIs() 和 searchAPI()
  2. 详情 Map (apiDetailMap): "METHOD /path" → 完整详情，用于 getAPIDetail() 的 O(1) 查找
  3. 首次加载: 调用 fetchSwaggerSpec() 时从远程获取规范并构建两层缓存
  4. 后续查询: 所有查询操作直接使用内存缓存，无需重新加载
  5. 会话管理: 调用 refreshSession() 可清空缓存

支持的 HTTP 方法

  • GET
  • POST
  • PUT
  • DELETE
  • PATCH
  • HEAD
  • OPTIONS

注意事项

  1. 需要网络连接来获取 Swagger 规范和调用 API
  2. 某些 API 可能需要身份验证，可通过 headers 参数传递认证信息
  3. 自然语言搜索基于关键词匹配，支持 summary、description、path、operationId 和 tags
  4. 路径参数需要在 query 参数中提供
  5. 文件上传:
    • 使用 uploadFile() 方法是最简单的方式，支持文件路径或 Buffer
    • 也可以使用 callAPI() 方法配合 FormData 对象进行更灵活的控制
    • 文件上传时不需要手动设置 Content-Type，会自动设置为 multipart/form-data
  6. 同时兼容 OpenAPI 3.0 (components.schemas) 和 Swagger 2.0 (definitions)

许可证

MIT

作者最新文章

如何将 Base64 编码的区块链交易载荷解析为结构化 Go 结构体

Singleton模式中饿汉式与懒汉式初始化的本质区别

React 中正确解析并排序 JSON API 数据的完整教程

JAX 中静态参数（static_argnames）与自动微分的冲突原理详解

Java 中单例模式的两种初始化方式：饿汉式与懒汉式详解

热门AI工具

更多
DeepSeek

DeepSeek

 小橡皮AI

小橡皮AI

Hot 火山引擎

火山引擎

Hot 豆包大模型

豆包大模型

 蛙蛙写作

蛙蛙写作

Hot UP简历

UP简历

Hot Laper

Laper

Hot Loomy

Loomy

Hot

相关专题

更多
Postman身份认证怎么配置
Postman身份认证怎么配置

本专题从实际API接口调试场景出发，讲解Postman身份认证的完整配置流程，包括常见认证协议介绍、授权参数设置、访问令牌填写、OAuth 2.0授权及认证失败排查，帮助用户正确完成接口授权与访问验证。

2026.11.06

0

12

Postman请求头Headers怎么设置
Postman请求头Headers怎么设置

围绕Postman HTTP请求头配置展开，讲解Headers选项的具体使用方式，包括Key和Value参数填写、请求头信息添加、常见Header字段设置及请求头修改方法，帮助用户解决接口调试过程中遇到的请求头配置问题。

2026.11.06

0

13

Postman接口请求发送教程
Postman接口请求发送教程

详细介绍Postman接口请求的创建与发送方法，涵盖GET和POST请求、URL配置、请求参数、Headers请求头、Body请求体设置以及响应结果查看，帮助用户掌握Postman接口请求的完整操作流程。

2026.11.06

0

10

DBeaver怎么导入数据
DBeaver怎么导入数据

DBeaver数据导入专题，整理Excel、CSV、SQL、TXT等常见文件的数据导入方法，涵盖目标数据库选择、数据表创建、字段映射、数据类型设置及导入参数配置等操作，帮助用户将本地文件中的数据写入数据库，并了解批量导入、重复数据处理和导入失败等常见问题的解决方法。

2026.11.05

0

12

DBeaver安全防护教程大全
DBeaver安全防护教程大全

DBeaver安全防护专题，围绕数据库连接安全、账号密码保护和访问权限管理展开，整理SSL/TLS加密连接、SSH隧道、数据库凭据保存及证书验证等配置方法，同时介绍敏感信息保护、远程连接风险和高权限账号使用等注意事项，帮助用户提高数据库日常管理的安全性。

2026.11.05

0

12

DBeaver连接创建与配置教程
DBeaver连接创建与配置教程

本专题聚焦DBeaver数据库连接配置与管理，覆盖从新建连接、选择数据库类型到填写连接参数和验证连接的完整流程。针对MySQL、PostgreSQL、SQL Server等常见数据库，整理相应的连接设置方法，并提供驱动缺失、认证失败和连接异常等问题的排查方向。

2026.11.04

0

16

XORM框架结构体映射与表结构同步
XORM框架结构体映射与表结构同步

本专题围绕XORM框架的结构体映射展开，说明表名与字段的命名策略、xorm标签常用属性、主键自增与时间字段自动填充，并演示Sync2自动建表、增量字段升级、索引声明与反向生成结构体的完整流程。

2026.11.04

0

15

XORM框架安装配置与数据库连接
XORM框架安装配置与数据库连接

本专题聚焦XORM框架的配置与连接环节，拆解MySQL、PostgreSQL、SQLite、SQL Server的DSN写法与驱动选择，讲清连接池参数、多数据源拆分、读写分离与超时重连的处理方式，并补充容器与兼容数据库的适配经验。

2026.11.04

0

15

XORM框架安装配置与数据库连接
XORM框架安装配置与数据库连接

本专题聚焦XORM框架的配置与连接环节，拆解MySQL、PostgreSQL、SQLite、SQL Server的DSN写法与驱动选择，讲清连接池参数、多数据源拆分、读写分离与超时重连的处理方式，并补充容器与兼容数据库的适配经验。

2026.11.04

0

16

热门下载

更多
网站特效
/
网站源码
/
网站素材
/
前端模板

相关下载

更多
MDPHP(麦迪php框架系统)1.1
PHP 多国语言框架2.0
ujframe简单快速PHP开发框架1.0
php轻量型框架1.0
MyQEE开源PHP多项目及模块化开发框架3.0 RC2
php开源学习型框架CMVC1.2.0
PHP框架Kohana3.3.1

精品课程

更多
热门推荐
/
最新课程
phpStudy极速入门视频教程
phpStudy极速入门视频教程

共6课时 | 54.7万人学习

独孤九贱(4)_PHP视频教程
独孤九贱(4)_PHP视频教程

共89课时 | 134.1万人学习

PHP实战天龙八部之仿爱奇艺电影网站
PHP实战天龙八部之仿爱奇艺电影网站

共49课时 | 82.6万人学习

最新文章

更多
火山引擎怎么限制一次请求的工具调用次数_火山引擎工具调用轮数控制指南
VibeKnow怎么替换视频中调色后的图片
讯飞绘文怎么把同一主题写给不同读者_讯飞绘文文章受众适配技巧
Lovart AI扩图后图片边缘变形怎么办_Lovart AI边界区域失真处理方法
讯飞绘文怎么通过原文快速完成内容仿写
码上飞AI怎么写取消按钮文案_码上飞AI取消操作表达建议
VibeKnow套餐升级划算吗？各版本权益对比分析
超级麦吉AI怎么让纪要保留结论形成的原因_超级麦吉AI会议决策依据整理方法
立刻MV怎么让副歌突出歌曲主题_立刻MV副歌主题强化方法
Lovart AI怎么让PPT配图不抢走文字重点_Lovart AI演示图文主次安排方法