📖 技能介紹

name: swagger-skill description: 智慧 Swagger API 查詢和呼叫工具。通過自然語言指令直接查詢介面詳情、呼叫 API，無需繁瑣的互動步驟。 metadata: clawdbot: emoji: "🏔️" requires: bins: ["node"]

小蔥技能有更好的技能skills外掛。

功能特性

一鍵查詢: 直接查詢介面詳情，自動解析引數、請求體、響應模式
自然語言搜尋: 根據自然語言描述找到匹配的介面（如"儲存使用者"、"獲取資料集列表"），支援 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 }
});

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 消耗：

輕量索引 (apiIndex): 僅儲存 path/method/summary/description/operationId/tags，用於 getAllAPIs() 和 searchAPI()
詳情 Map (apiDetailMap): "METHOD /path" → 完整詳情，用於 getAPIDetail() 的 O(1) 查詢
首次載入: 呼叫 fetchSwaggerSpec() 時從遠端獲取規範並構建兩層快取
後續查詢: 所有查詢操作直接使用記憶體快取，無需重新載入
會話管理: 呼叫 refreshSession() 可清空快取

支援的 HTTP 方法

GET
POST
PUT
DELETE
PATCH
HEAD
OPTIONS

注意事項

需要網路連線來獲取 Swagger 規範和呼叫 API
某些 API 可能需要身份驗證，可通過 headers 引數傳遞認證資訊
自然語言搜尋基於關鍵詞匹配，支援 summary、description、path、operationId 和 tags
路徑引數需要在 query 引數中提供
檔案上傳:
使用 uploadFile() 方法是最簡單的方式，支援檔案路徑或 Buffer
也可以使用 callAPI() 方法配合 FormData 物件進行更靈活的控制
檔案上傳時不需要手動設定 Content-Type，會自動設定為 multipart/form-data
同時相容 OpenAPI 3.0 (components.schemas) 和 Swagger 2.0 (definitions)

許可證

MIT

🤖 AI 評測

這個 Skill 質量較好，能幫助使用者快速查詢和呼叫 Swagger API，支援中文搜尋和多種認證方式，CLI 操作也比較直觀。主要問題是文件說明不完整，部分內容缺失；自動安裝依賴的設計存在一定安全風險。總體適合有經驗的開發者使用，但普通使用者需要謹慎評估後再使用。

📊 多維度評分

適應性4.4

規範性4.3

有效性4.6

可靠性4.6

可信度5

📁 包含檔案 (5 個)

📄 SKILL.md 10.8 KB

📄 _meta.json 132 B

📄 cli.js 7.1 KB

📄 index.js 14.1 KB

📄 skill-card.md 1.9 KB

swagger-skill

📖 技能介紹

功能特性

安裝

使用方法

基礎使用

認證方法

方法 1: 使用 Token 認證

方法 2: 使用 Cookie 認證

方法 3: 無需認證

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

API 文件

fetchSwaggerSpec(url, options)

setAuthToken(token, options)

setAuthCookies(cookies)

clearAuth()

getAllAPIs()

searchAPI(query)

getAPIDetail(path, method)

getFullAPIDetail(path, method)

callAPI(path, method, params)

callAPIByInstruction(instruction, params)

uploadFile(path, formData, query)

getSessionId()

refreshSession()

快取機制

支援的 HTTP 方法

注意事項

許可證

🤖 AI 評測

📊 多維度評分

📁 包含檔案 (5 個)

🔗 相關推薦