API Document Management and API Test
개요
API 문서를 적절히 관리하는 것은 개발자 온보딩, 테스트 및 통합에 매우 중요합니다. APIM은 OpenAPI 사양을 첨부하거나 문서를 수동으로 정의한 다음, 인터페이스 내에서 즉시 API를 테스트할 수 있도록 합니다. 이 튜토리얼에서는 샘플 구성을 사용하여 배포된 API에 대한 문서를 업로드/편집하고 테스트를 실행하는 방법을 보여줍니다.
필수 조건
다음이 필요합니다:
- 배포된 API 버전 (예: user-service-api v1.0)
- 편집자 또는 관리자 권한이 있는 APIM 콘솔에 대한 액세스
- 수동으로 작성하는 경우 OpenAPI 사양 파일 또는 API 정의 세부정보
단계별 튜토리얼
단계 1. API 버전 세부정보 페이지 열기
- API 관리로 이동
- user-service-api 선택
- 버전 v1.0 선택
단계 2. API 문서 업로드 또는 편집
두 가지 옵션이 있습니다:
옵션 A: OpenAPI 업로드 (YAML/JSON)
- 가져오기 클릭
- OpenAPI 3.0 파일(예: user-service-v1.yaml)을 선택하고 업로드
- 시스템이 모든 엔드포인트와 설명을 파싱하고 업데이트합니다.
옵션 B: 수동 API 정의
OpenAPI 파일이 없는 경우:
- 문서 탭에서 편집 클릭
- 세부정보를 수동으로 추가: | 필드 | 예시 | | --- | --- | | 요약 | 사용자 로그인 엔드포인트 | | 메서드 | POST | | 경로 | /login | | 요청 본문 | 사용자 이름, 비밀번호가 포함된 JSON | | 응답 | 200 OK + JSON 본문 |
완료되면 저장 클릭.
단계 3. 내장 테스트기를 사용하여 API 테스트
API 버전 세부정보 페이지에서 테스트 탭으로 이동:
필드 | 값 |
---|---|
대상 메서드 | POST |
경로 | /v1/login |
헤더 | Content-Type: application/json |
본문 예시:
{
"username": "jane.doe",
"password": "test1234"
}
요청 보내기 클릭
단계 4. 테스트 결과 검토
예상 응답:
```json
{
"userId": "12345",
"token": "eyJhbGciOi..."
}
콘솔은 다음을 표시합니다:
- HTTP 상태 코드 (예: 200 OK)
- 소요 시간
- 요청 및 응답 본문
일반적인 문제 및 문제 해결
문제 | 원인 | 해결책 |
---|---|---|
유효하지 않은 OpenAPI 파일 | 구문 오류 또는 지원되지 않는 필드 | Swagger Editor를 사용하여 검증 |
테스트에서 응답 없음 | 잘못된 경로 또는 백엔드 누락 | 게이트웨이 경로 및 백엔드 상태를 다시 확인 |
401 권한 없음 | API 키 또는 인증 정책 누락 | Authorization 헤더를 설정하거나 인증을 일시적으로 비활성화 |
415 지원되지 않는 미디어 유형 | Content-Type 누락 또는 잘못됨 | 본문 요청에 application/json 사용 |
모범 사례
- 정확한 문서를 위해 항상 검증된 OpenAPI 사양을 업로드
- 모든 엔드포인트에 대한 예제 요청/응답 추가
- 외부 소비자와 API를 공유하기 전에 내장 테스트기를 사용
- 성공 사례뿐만 아니라 오류 응답(4xx/5xx) 문서화
- API 수명 주기와 함께 API 문서를 버전 관리