본문으로 건너뛰기

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 문서를 버전 관리