AI导哈

Swagger API聊天工具

通过聊天界面探索和测试Swagger/OpenAPI文档的API开发工具，无需使用Postman。

  • by ongjin
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 ongjin/swagger-mcp

使用说明

🔌 Swagger MCP服务器

与人工智能聊天，探索Swagger/OpenAPI并直接测试API。API通过聊天进行开发，不需要Postman。

韩语 | 📚 文档

为什么？

在MSA环境中的多个API文档之间导航是单调乏味的。

使用此MCP服务器：

  • 🔄 无缝服务切换 -只需说“连接到支付服务器”
  • 🧪 API直接测试 -直接从聊天中调用API，无需邮递员
  • 📋 自动生成cURL -复制并粘贴到终端
  • 📊 模式/DTO检查 -用于TypeScript接口生成
  • ⚡ 动态URL支持 -直接输入URL，无需配置

✨ 可用工具

🔌 服务管理

工具 说明
swagger_select_service 选择服务（配置别名或直接URL）
swagger_list_services 列出所有已配置的服务
swagger_get_current 显示当前服务信息

🔍 API发现

工具 说明
swagger_list_endpoints 列出所有端点（按标签筛选）
swagger_get_endpoint 获取端点详细信息（参数、正文、响应）
swagger_search 按关键字搜索端点

📊 架构检查

工具 说明
swagger_get_schema 获取架构/DTO结构
swagger_list_schemas 列出所有可用架构

🧪 API测试

工具 说明
swagger_test 执行实际的HTTP请求
swagger_curl 生成cURL命令

🛠️ 代码生成

工具 说明
swagger_generate_code 生成Types/axios代码

📦 可用资源

资源提供了Claude可以作为上下文访问的只读数据。

资源URI 描述
swagger://services 已配置服务列表
swagger://current/info 当前服务信息
swagger://current/endpoints 当前服务中的所有端点
swagger://current/schemas 当前服务中的所有模式/DTO

💡 小贴士：在Claude Desktop中，使用 @ 将资源附加到您的消息中以获取上下文。

🚀 安装

# No installation required
npx @zerry_jin/swagger-mcp

# Or install globally
npm install -g @zerry_jin/swagger-mcp

⚙️ 配置

克劳德代码（CLI）

# Register MCP server
claude mcp add swagger-mcp -- npx @zerry_jin/swagger-mcp -s project

# Verify
claude mcp list

Claude桌面应用程序

添加 claude_desktop_config.json:

📁 Config file locations
操作系统 路径
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
窗户 %APPDATA%\Claude\claude_desktop_config.json
Linux ~/.config/Claude/claude_desktop_config.json 
{
  "mcpServers": {
    "swagger-mcp": {
      "command": "npx",
      "args": ["-y", "@zerry_jin/swagger-mcp"]
    }
  }
}

📋 服务配置（swagg-targets.json）

创建 swagger-targets.json 在项目根目录中快速切换服务：

{
  "auth": "http://localhost:3000/api-docs",
  "payment": "http://localhost:3001/api-docs",
  "order": "http://localhost:3002/api-docs",
  "petstore": "https://petstore.swagger.io/v2/swagger.json",
  "local": "./docs/openapi.yaml"
}

带基本URL的扩展配置

对于像WSL/Docker这样API服务器URL与规范URL不同的环境：

{
  "core": {
    "spec": "http://host.docker.internal:8080/v3/api-docs",
    "baseUrl": "http://localhost:8080"
  },
  "payment": {
    "spec": "./specs/payment.json",
    "baseUrl": "http://localhost:3001"
  }
}

这 baseUrl 将自动用于 swagger_test 和 swagger_curl 命令。

现在，您可以按名称切换服务：

You: Connect to payment service
Claude: ✅ Connected to "payment" (http://localhost:3001/api-docs)

配置搜索顺序

  1. --config 论点 -显式路径
  2. SWAGGER_MCP_CONFIG -环境变量
  3. 当前工作目录
  4. ~/.swagger-mcp/swagger-targets.json -主页目录

💡 小贴士：对于Claude Desktop，请使用 --config 要指定项目路径，请执行以下操作：

"args": ["-y", "@zerry_jin/swagger-mcp", "--config", "/path/to/project"]

🎯 快速权限设置

克劳德代码（CLI）

# In claude, type:
/permissions

# Add to Allowed Tools:
mcp__swagger-mcp__*

Claude桌面应用程序

检查 “始终允许来自此服务器的请求” 第一次使用工具。

💡 使用示例

1.️⃣ 选择服务

You: Connect to the petstore API

Claude: [swagger_select_service name="petstore"]

✅ Connected to "petstore"
- Title: Swagger Petstore
- Version: 1.0.0
- Endpoints: 20
- Tags: pet, store, user

2.️⃣ 列出端点

You: Show me all pet endpoints

Claude: [swagger_list_endpoints tag="pet"]

🏷️ 8 endpoints tagged "pet":
| Method | Path | Summary |
|--------|------|---------|
| POST | /pet | Add a new pet |
| PUT | /pet | Update a pet |
| GET | /pet/findByStatus | Find by status |
| GET | /pet/{petId} | Find by ID |
| DELETE | /pet/{petId} | Delete a pet |
...

3.️⃣ 获取端点详细信息

You: Show me POST /pet details

Claude: [swagger_get_endpoint method="post" path="/pet"]

📖 POST /pet - Add a new pet to the store

Request Body (application/json):
{
  "name": string (required),
  "photoUrls": string[] (required),
  "status": "available" | "pending" | "sold"
}

Responses:
- 200: Successful
- 405: Invalid input

4.️⃣ 获取架构/DTO

You: Show me the Pet schema

Claude: [swagger_get_schema schemaName="Pet"]

📊 Pet Schema:
{
  "type": "object",
  "required": ["name", "photoUrls"],
  "properties": {
    "id": { "type": "integer" },
    "name": { "type": "string" },
    "category": { "$ref": "#/definitions/Category" },
    "photoUrls": { "type": "array", "items": { "type": "string" } },
    "status": { "enum": ["available", "pending", "sold"] }
  }
}

5.️⃣ 测试API(🔥 不需要邮递员！)

You: Call GET /pet/1

Claude: [swagger_test method="GET" path="/pet/{petId}" pathParams={"petId":"1"}]

🧪 API Test Result:

Request: GET /pet/1
Status: 200 OK
Duration: 127ms

Response:
{
  "id": 1,
  "name": "doggie",
  "status": "available"
}

cURL:
curl 'https://petstore.swagger.io/v2/pet/1'

6.️⃣ 生成cURL

You: Generate curl for creating a pet

Claude: [swagger_curl method="POST" path="/pet" body={...}]

📋 cURL Command:

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "doggie",
    "photoUrls": ["https://example.com/photo.jpg"],
    "status": "available"
  }' \
  'https://petstore.swagger.io/v2/pet'

7.️⃣ 交换机服务

You: Now connect to the payment service

Claude: [swagger_select_service name="payment"]

✅ Switched to "payment" (http://localhost:3001/api-docs)
- Title: Payment API
- Endpoints: 12

8.️⃣ 生成TypeScript代码(🔥 新)

You: Generate TypeScript code for POST /pet

Claude: [swagger_generate_code method="post" path="/pet"]

📝 Generated TypeScript Code:

import axios, { AxiosResponse } from 'axios';

interface PostPetRequest {
  name: string;
  photoUrls: string[];
  status?: string;
}

/**
 * Add a new pet to the store
 */
export async function postPet(data: PostPetRequest): Promise<AxiosResponse> {
  const url = `${BASE_URL}/pet`;
  return axios.post(url, data);
}

// Note: Define BASE_URL constant or import from config
// const BASE_URL = 'http://localhost:8080';

🔧 支持的规格

格式 版本
OpenAPI 3.0.x，3.1.x
Swagger 2.0

🏗️ 建筑

src/
├── index.ts                 # MCP server entry
├── services/
│   ├── config-loader.ts     # swagger-targets.json loader
│   ├── swagger-parser.ts    # OpenAPI parsing
│   └── http-client.ts       # API testing & cURL generation
├── tools/
│   └── swagger-tools.ts     # 11 MCP tools
└── types/
    └── swagger.ts           # TypeScript definitions

📚 文档

https://ongjin.github.io/swagger-mcp

🤝 贡献

欢迎投稿！

  • 🐛 错误报告
  • 💡 功能建议
  • 🔧 拉取请求

📄 许可证

MIT许可证

由以下材料制成❤️ 通过 泽里

相关 MCP