AI导哈

API代码生成服务

Swagger MCP Server是一个后端API的Swagger文档服务，通过LLM技术使开发人员能够使用自然语言搜索API并自动生成完整的网络代码。

  • by WooJJam
  • Java
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 WooJJam/swagger-mcp-server

使用说明

Swagger MCP服务器

将Backend API的Swagger文档作为MCP服务器提供，客户端开发人员在Claude Code中 用自然语言搜索API和 自动生成完整的网络代码允许的系统。

通过基于LLM的查询取代了以往直接浏览Swagger UI并查看端点、请求/响应结构的过程，从而缩短了过程。

创建Swagger MCP Server第1篇-基于LLM的API导航自动化设计

创建Swagger MCP Server第2篇-解析Swagger API

创建Swagger MCP Server第3篇-数据库存储设计和故障排除

创建Swagger MCP Server第4篇-使用Spring AI构建MCP服务器，并与Claude Code集成

关键点

개발자: "로그인 API 찾아서 DTO 만들어줘"
    ↓
Claude가 자동으로:
1. searchApiByKeyword("로그인") 호출 → API 찾기
2. getApiDetail(apiId) 호출 → Request/Response 스키마 조회
3. 즉시 Kotlin/Swift DTO 코드 생성 + 네트워크 호출 코드 작성

用法

前提条件

  • Java 21+
  • 码头工人

本地运行

# 1. .env 파일 생성
cp .env.example .env  # 값 채워넣기

# 2. 컨테이너 실행 (MySQL + App)
docker compose up -d

# 3. 또는 로컬 직접 실행
./gradlew bootRun

.env设置值

MYSQL_ROOT_PASSWORD=
MYSQL_DATABASE=
MYSQL_USER=
MYSQL_PASSWORD=
MCP_ACCESS_TOKEN=
APP_IMAGE=

MCP端点

GET /mcp
Authorization: Bearer {MCP_ACCESS_TOKEN}

Claude Code连接

claude mcp add --transport http swagger-mcp http://{SERVER_IP}:{SERVER_PORT}/mcp \
  --header "Authorization: Bearer {MCP_ACCESS_TOKEN}" --scope project

特性

1.Swagger解析和数据库存储

  • 从Backend服务器下载和解析OpenAPI 3.0 JSON
  • $ref 决心 #/components/schemas/LoginRequest →转换为实际的schema结构
  • 将API端点、Request/Response/Error架构结构化存储在SQL中
  • 解析NDGL错误代码格式： DOMAIN-CATEGORY-DETAIL

2.提供MCP工具（Spring AI MCP）

  • searchApiBy关键字：使用关键字搜索API（path、summary、tags）
  • getApi详情：查询API详细信息（包括请求、响应和错误）
  • Getrequisites格式：返回Request DTO模式
  • getResponse格式：返回Success Response DTO模式
  • getErrorFormats：返回Error Response列表

3.AI友好型响应格式

  • DB存储格式→转换为AI易于理解的结构（SchemaSupporter）
  • 明确区分嵌套对象、数组类型和Required/Optional字段
  • 提供Example值可立即生成代码

🏗️ 架构

四层架构

Controller → Facade(UseCase) → Service → Repository
  • 控制器：HTTP请求/响应处理，仅依赖于UseCase
  • 用例（正面）：多个服务组合（orchestration）
  • 服务：基于单一责任原则的细分业务逻辑
  • 仓库：基于Spring Data JPA的数据访问

Swagger同步流

SyncController
    ↓
SyncSwaggerUseCase (Facade)
    ├─→ SwaggerFetchService     (Swagger JSON 다운로드)
    ├─→ SwaggerExtractorService (메타데이터 추출)
    ├─→ SwaggerParserService    (파싱 오케스트레이션)
    │       ├─ EndpointBasicInfoParser
    │       ├─ RequestSchemaParser  ($ref resolution)
    │       ├─ ResponseSchemaParser ($ref resolution)
    │       ├─ ErrorResponseParser  ($ref resolution, 에러 코드 파싱)
    │       └─ TagParser
    └─→ SwaggerSyncService      (DB 저장)

MCP查询流程

Claude Code
    ↓
SwaggerMcpTools (@Tool)
    ↓
ApiSearchService
    ├─→ Repository (DB 조회)
    └─→ SchemaSupporter (DB 포맷 → AI 친화적 포맷)

🛠️ 技术堆栈

类别 技术
框架 Spring Boot 3.5.9
语言 Java 21
数据库 MySQL 8.0
ORM 春季数据JPA
MCP Spring AI MCP 1.1.2
解析器 Jackson，Swagger解析器2.1.37
公用事业 龙目岛
部署 Docker、GitHub操作

项目结构

src/main/java/com/ndgl/swaggermcp/
├── sync/                          # Swagger 동기화 도메인
│   ├── presentation/http/
│   │   └── SyncController
│   ├── application/
│   │   ├── usecase/
│   │   │   └── SyncSwaggerUseCase  (Facade)
│   │   ├── service/
│   │   │   ├── SwaggerFetchService
│   │   │   ├── SwaggerParserService
│   │   │   ├── SwaggerExtractorService
│   │   │   └── SwaggerSyncService
│   │   └── parser/
│   │       ├── EndpointBasicInfoParser
│   │       ├── RequestSchemaParser
│   │       ├── ResponseSchemaParser
│   │       ├── ErrorResponseParser
│   │       └── TagParser
│   ├── support/
│   │   └── JsonSchemaParsingSupport  ($ref 해석, Example 추출)
│   └── dto/
│       ├── ParsedApiEndpoint
│       ├── ParsedRequestBody
│       ├── ParsedParameter
│       ├── ParsedResponseSchema
│       └── ParsedErrorResponse
│
├── ai/                            # MCP 서버 도메인
│   ├── presentation/mcp/
│   │   └── SwaggerMcpTools        (MCP Tool 구현)
│   ├── service/
│   │   └── ApiSearchService
│   ├── support/
│   │   └── SchemaSupporter        (DB 포맷 → AI 친화적 포맷)
│   └── dto/
│       ├── ApiDetailForAI
│       ├── RequestForAI
│       ├── ResponseForAI
│       ├── ErrorForAI
│       ├── FieldInfo
│       ├── ParameterInfo
│       └── ApiSummary
│
├── persistence/                   # 데이터 접근 계층
│   ├── entity/
│   │   ├── ApiEndpoint
│   │   ├── RequestSchema
│   │   ├── Parameter
│   │   ├── ResponseSchema
│   │   ├── ErrorResponse
│   │   └── SwaggerMetadata
│   └── repository/
│
└── common/
    ├── config/
    │   ├── JpaConfig
    │   └── RestClientConfig
    └── filter/
        └── ApiKeyAuthFilter       (MCP 인증)

MCP工具规范

1. searchApiByKeyword(keyword: String)

说明：使用关键字搜索API 搜索对象：路径、摘要、描述、操作ID 返还: List<ApiSummary> （id、方法、路径、摘要、标签）

例子:

searchApiByKeyword("로그인")
→ [
    {
      "id": 1,
      "method": "POST",
      "path": "/api/v1/auth/login",
      "summary": "사용자 로그인",
      "tags": ["인증"]
    }
  ]

2. getApiDetail(apiId: Long)

说明：查询API详细信息（包括请求、响应和错误） 返还: ApiDetailForAI

响应结构:

{
  "id": 1,
  "method": "POST",
  "path": "/api/v1/auth/login",
  "summary": "사용자 로그인",
  "request": {
    "body": {
      "email": {"type": "string", "required": true, "example": "user@example.com"},
      "password": {"type": "string", "required": true, "example": "password123"}
    },
    "parameters": []
  },
  "responses": {
    "200": {"fields": {"accessToken": {"type": "string"}, "refreshToken": {"type": "string"}}}
  },
  "errors": {
    "401": {"code": "AUTH-LOGIN-INVALID_CREDENTIALS", "message": "인증 실패"}
  }
}

3. getRequestFormat(apiId: Long)

说明：请求Body+Parameters查询/ 返还: RequestForAI

4. getResponseFormat(apiId: Long)

说明：按状态代码查看Success Response/ 返还: Map<Integer, ResponseForAI>

5. getErrorFormats(apiId: Long)

说明：按状态代码查询Error Response/ 返还: Map<Integer, ErrorForAI>

相关 MCP