Backend APIμ Swagger λ¬Έμλ₯Ό MCP μλ²λ‘ μ 곡νμ¬, ν΄λΌμ΄μΈνΈ κ°λ°μκ° Claude Codeμμ μμ°μ΄λ‘ APIλ₯Ό κ²μνκ³ μμ ν λ€νΈμνΉ μ½λλ₯Ό μλ μμ±ν μ μλλ‘ νλ μμ€ν μ λλ€.
κΈ°μ‘΄μ Swagger UIλ₯Ό μ§μ νμνλ©° μλν¬μΈνΈ, μμ²/μλ΅ κ΅¬μ‘°λ₯Ό νμΈνλ κ³Όμ μ LLM κΈ°λ° μ‘°νλ‘ λμ²΄ν΄ λ¨μΆν©λλ€.
κ°λ°μ: "λ‘κ·ΈμΈ API μ°Ύμμ DTO λ§λ€μ΄μ€"
β
Claudeκ° μλμΌλ‘:
1. searchApiByKeyword("λ‘κ·ΈμΈ") νΈμΆ β API μ°ΎκΈ°
2. getApiDetail(apiId) νΈμΆ β Request/Response μ€ν€λ§ μ‘°ν
3. μ¦μ Front-end DTO μ½λ μμ± + λ€νΈμν¬ νΈμΆ μ½λ μμ±
- Backend μλ²μ OpenAPI 3.0 JSON λ€μ΄λ‘λ λ° νμ±
$refResolution:#/components/schemas/LoginRequestβ μ€μ schema κ΅¬μ‘°λ‘ λ³ν- API μλν¬μΈνΈ, Request/Response/Error μ€ν€λ§λ₯Ό MySQLμ ꡬ쑰ν μ μ₯
- μλ¬ μ½λ νμ νμ±:
DOMAIN-CATEGORY-DETAIL
- searchApiByKeyword: ν€μλλ‘ API κ²μ (path, summary, description, operationId)
- getApiDetail: API μμΈ μ 보 μ‘°ν (Request, Response, Error ν¬ν¨)
- getRequestFormat: Request DTO μ€ν€λ§ λ°ν
- getResponseFormat: Success Response DTO μ€ν€λ§ λ°ν
- getErrorFormats: Error Response λͺ©λ‘ λ°ν
- DB μ μ₯ ν¬λ§· β AIκ° μ΄ν΄νκΈ° μ¬μ΄ κ΅¬μ‘°λ‘ λ³ν (SchemaSupporter)
- μ€μ²© κ°μ²΄, λ°°μ΄ νμ , Required/Optional νλ λͺ ννκ² κ΅¬λΆ
- Example κ° μ 곡μΌλ‘ μ¦μ μ½λ μμ± κ°λ₯
Controller β Facade(UseCase) β Service β Repository
- Controller: HTTP μμ²/μλ΅ μ²λ¦¬, UseCaseλ§ μμ‘΄
- UseCase(Facade): μ¬λ¬ Service μ‘°ν© (orchestration)
- Service: λ¨μΌ μ± μ μμΉμ λ°λ₯Έ μΈλΆνλ λΉμ¦λμ€ λ‘μ§
- Repository: Spring Data JPA κΈ°λ° λ°μ΄ν° μ κ·Ό
SyncController
β
SyncSwaggerUseCase (Facade)
βββ SwaggerFetchService (Swagger JSON λ€μ΄λ‘λ)
βββ SwaggerExtractorService (λ©νλ°μ΄ν° μΆμΆ)
βββ SwaggerParserService (νμ± μ€μΌμ€νΈλ μ΄μ
)
β ββ EndpointBasicInfoParser
β ββ RequestSchemaParser ($ref resolution)
β ββ ResponseSchemaParser ($ref resolution)
β ββ ErrorResponseParser ($ref resolution, μλ¬ μ½λ νμ±)
βββ SwaggerSyncService (DB μ μ₯)
Claude Code
β
SwaggerMcpTools (@McpTool)
β
ApiSearchService
βββ Repository (DB μ‘°ν)
βββ SchemaSupporter (DB ν¬λ§· β AI μΉνμ ν¬λ§·)
| μΉ΄ν κ³ λ¦¬ | κΈ°μ |
|---|---|
| Framework | Spring Boot 3.5.9 |
| Language | Java 21 |
| Database | MySQL 8.0 |
| ORM | Spring Data JPA |
| MCP | Spring AI MCP 1.1.2 |
| Parser | Jackson, Swagger Parser 2.1.40 |
| Utility | Lombok |
| Deploy | Docker, GitHub Actions |
src/main/java/com/kimjiwon/apispecmcp/
βββ sync/ # Swagger λκΈ°ν λλ©μΈ
β βββ presentation/http/
β β βββ SyncController
β βββ application/
β β βββ usecase/
β β β βββ SyncSwaggerUseCase (Facade)
β β βββ service/
β β β βββ SwaggerFetchService
β β β βββ SwaggerParserService
β β β βββ SwaggerExtractorService
β β β βββ SwaggerSyncService
β β βββ parser/
β β βββ EndpointBasicInfoParser
β β βββ RequestSchemaParser
β β βββ ResponseSchemaParser
β β βββ ErrorResponseParser
β βββ utils/
β β βββ JsonSchemaParsingUtil ($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
β βββ JacksonConfig
β βββ RestClientConfig
βββ filter/
βββ ApiKeyAuthFilter (MCP μΈμ¦)
μ€λͺ
: ν€μλλ‘ API κ²μ
κ²μ λμ: path, summary, description, operationId
λ°ν: List<ApiSummary> (id, method, path, summary, tags)
μμ:
searchApiByKeyword("λ‘κ·ΈμΈ")
β [
{
"id": 1,
"method": "POST",
"path": "/api/v1/auth/login",
"summary": "μ¬μ©μ λ‘κ·ΈμΈ",
"tags": ["μΈμ¦"]
}
]μ€λͺ
: API μμΈ μ 보 μ‘°ν (Request, Response, Error ν¬ν¨)
λ°ν: 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": "μΈμ¦ μ€ν¨"}
}
}μ€λͺ
: Request Body + Parameters μ‘°ν / λ°ν: RequestForAI
μ€λͺ
: μν μ½λλ³ Success Response μ‘°ν / λ°ν: Map<Integer, ResponseForAI>
μ€λͺ
: μν μ½λλ³ Error Response μ‘°ν / λ°ν: Map<Integer, ErrorForAI>
- Java 21+
- Docker
# 1. .env νμΌ μμ±
cp .env.example .env # κ° μ±μλ£κΈ°
# 2. 컨ν
μ΄λ μ€ν (MySQL + App)
docker compose up -d
# 3. λλ λ‘컬 μ§μ μ€ν
./gradlew bootRunMYSQL_ROOT_PASSWORD=
MYSQL_DATABASE=
MYSQL_USER=
MYSQL_PASSWORD=
MCP_ACCESS_TOKEN=
APP_IMAGE=
GET /mcp
Authorization: Bearer {MCP_ACCESS_TOKEN}claude mcp add --transport http swagger-mcp http://{SERVER_IP}:{SERVER_PORT}/mcp \
--header "Authorization: Bearer {MCP_ACCESS_TOKEN}" --scope project