예제 & 모범 사례

Swagger MCP 서버의 실제 사용 예제와 모범 사례입니다.

일반적인 워크플로우

새로운 API 탐색하기

새로운 API를 접할 때 다음 워크플로우를 따르세요:

1. "https://petstore.swagger.io/v2/swagger.json에 연결해줘"
   → 연결 수립 및 API 개요 표시

2. "모든 엔드포인트 보여줘"
   → 태그별로 정리된 모든 엔드포인트 표시

3. "'pet' 태그가 달린 엔드포인트 보여줘"
   → 특정 카테고리로 필터링

4. "POST /pet 상세 정보 알려줘"
   → 파라미터, 요청 바디, 응답 표시

5. "Pet 스키마 보여줘"
   → TypeScript/유효성 검증용 데이터 구조 표시

전체 대화 예시:

사용자: petstore API에 연결해줘

Claude: ✅ "petstore"에 연결됨
- 제목: Swagger Petstore
- 버전: 1.0.6
- 엔드포인트: 20개
- 태그: pet, store, user

사용자: pet 관련 엔드포인트가 뭐가 있어?

Claude: 🏷️ "pet" 태그 8개 엔드포인트:
| 메서드 | 경로 | 요약 |
|--------|------|------|
| POST | /pet | 새 펫 추가 |
| PUT | /pet | 펫 수정 |
| GET | /pet/findByStatus | 상태로 검색 |
...

사용자: 펫을 어떻게 생성해?

Claude: 📖 POST /pet - 스토어에 새 펫 추가

요청 바디 (필수):
{
  "name": string (필수),
  "photoUrls": string[] (필수),
  "status": "available" | "pending" | "sold"
}

---

API 엔드포인트 테스트하기

채팅을 떠나지 않고 바로 엔드포인트를 테스트하세요:

1. "petstore에 연결해줘"
   → 서비스 연결

2. "GET /pet/1 호출해봐"
   → 실제 요청 실행, 응답 확인

3. "name이 'buddy'이고 status가 'available'인 POST /pet 테스트해봐"
   → 새 리소스 생성

전체 대화 예시:

사용자: GET /pet/1 호출해봐

Claude: 🧪 API 테스트 결과:

요청: GET /pet/1
상태: 200 OK
소요시간: 127ms

응답:
{
  "id": 1,
  "name": "doggie",
  "status": "available"
}

사용자: 이제 "Max"라는 새 펫 생성해봐

Claude: 🧪 API 테스트 결과:

요청: POST /pet
상태: 200 OK
소요시간: 234ms

응답:
{
  "id": 9223372036854775807,
  "name": "Max",
  "status": "available"
}

---

cURL 명령어 생성하기

터미널이나 스크립트용 cURL을 생성하세요:

1. "payment 서비스에 연결해줘"
2. "POST /orders 엔드포인트 보여줘"
3. "amount가 100인 주문 생성 curl 명령어 만들어줘"

전체 대화 예시:

사용자: 펫 생성 curl 만들어줘

Claude: 📋 cURL 명령어:

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'

---

MSA 환경 워크플로우

여러 서비스 간 원활하게 전환하세요:

1. "등록된 서비스 목록 보여줘"
   → 설정된 모든 서비스 확인

2. "auth 서비스에 연결해줘"
   → 인증 API 작업

3. "로그인 엔드포인트 보여줘"
   → 인증 엔드포인트 탐색

4. "이제 payment 서비스로 전환해줘"
   → 다른 서비스로 컨텍스트 변경

5. "'refund' 엔드포인트 검색해줘"
   → 새 서비스에서 관련 엔드포인트 찾기

전체 대화 예시:

사용자: 어떤 서비스가 있어?

Claude: 📋 등록된 서비스 (4개):
- 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

사용자: payment 서비스에 연결해줘

Claude: ✅ "payment"에 연결됨
- 제목: Payment API
- 엔드포인트: 12개
- 태그: payments, refunds, webhooks

사용자: refund 엔드포인트 검색해줘

Claude: 🔍 "refund" 검색 결과 3개:
| 메서드 | 경로 | 요약 |
|--------|------|------|
| POST | /refunds | 환불 생성 |
| GET | /refunds/{id} | 환불 상태 조회 |
| GET | /payments/{id}/refunds | 결제의 환불 목록 |

---

API 문서 검토

체계적으로 API 문서를 검토하세요:

1. "API에 연결하고 현재 정보 보여줘"
2. "deprecated된 엔드포인트 있어?"
3. "모든 스키마 보여줘"
4. "어떤 인증이 필요해?"

---

모범 사례

서비스 설정

swagger-targets.json 사용하기

프로젝트 루트에 swagger-targets.json 파일을 생성하여 빠르게 서비스를 전환하세요:

{
  "auth": "http://localhost:3000/api-docs",
  "payment": "http://localhost:3001/api-docs",
  "staging": "https://staging-api.example.com/docs"
}

여러 서비스 간 자주 전환하는 MSA 환경에서 특히 유용합니다.

캐싱 동작

스펙 캐싱

스펙은 첫 번째 가져오기 후 캐시됩니다. 새로고침하려면:

• 동일한 서비스에 다시 연결
• 서버 재시작 시 캐시가 초기화됨

URL 형식

항상 프로토콜 포함

직접 URL을 사용할 때는 항상 전체 프로토콜을 포함하세요:

✅ "https://api.example.com/docs에 연결해줘"
✅ "http://localhost:3000/api-docs 사용해줘"
❌ "api.example.com/docs에 연결해줘"

API 테스트 안전

변경 작업 주의

swagger_test 도구는 실제 HTTP 요청을 실행합니다. 다음 경우에 주의하세요:

• POST, PUT, DELETE 엔드포인트 테스트 시
• 프로덕션 API 작업 시
• 민감한 데이터 처리 시

테스트에는 스테이징 환경 사용을 고려하세요.

TypeScript 인터페이스 생성

스키마를 TypeScript로

TypeScript 인터페이스 생성에 스키마를 활용하세요:

사용자: Pet 스키마를 TypeScript 인터페이스로 변환해줘

Claude:
interface Pet {
  id?: number;
  name: string;
  category?: Category;
  photoUrls: string[];
  status?: 'available' | 'pending' | 'sold';
}

효율적인 탐색

태그로 탐색하기

대부분의 API는 태그로 엔드포인트를 구성합니다. 태그 필터링을 사용하세요:

"'user' 엔드포인트 보여줘"
"'authentication' 태그가 달린 엔드포인트 보여줘"

모든 엔드포인트를 나열하는 것보다 효율적입니다.