Swagger로 관리되는 API를 Apidog로 마이그레이션하는 데는 여러 가지 방법이 있습니다. 이 가이드에서는 Swagger 파일을 내보내 Apidog에 가져오는 네 가지 주요 방법을 설명합니다.
Swagger로 관리되는 API를 Apidog로 마이그레이션하는 방법에는 여러 가지가 있습니다. 이 가이드에서는 Swagger 파일을 Apidog에 가져오는 4가지 간단한 방법을 설명합니다. 방법에는 온라인 링크를 통한 예약된 가져오기, IDEA 플러그인을 사용한 원클릭 업로드, Open API를 통한 가져오기가 포함됩니다. 각 방법에 대한 자세한 단계는 아래에 나와 있습니다.
방법 1: Swagger 파일 내보내기 및 Apidog로 가져오기
이 방법은 가장 간단한 접근 방식으로, 특히 API 문서가 안정적일 때 일회성 마이그레이션에 적합합니다. 아래는 구체적인 단계입니다:
1단계. Swagger 파일 내보내기
Swagger UI에서 API 문서를 .yaml 또는 .json 파일로 내보냅니다. 일반적으로 Swagger UI의 왼쪽 상단에서 파일을 다운로드하는 옵션을 찾을 수 있습니다.
인터페이스에 URL 링크가 표시되지 않는 경우, "F12" 또는 "Ctrl+Shift+I"를 눌러 브라우저 콘솔을 열고, "Network" -> "Fetch/XHR"로 이동한 다음 페이지를 새로 고침합니다. 그러면 .json 파일이 표시되며, 이를 새 창에서 열어 다운로드할 수 있습니다.
2단계. Swagger 문서 Apidog에 가져오기
Apidog을 열고, 프로젝트로 이동한 후, 프로젝트 설정 -> 데이터 가져오기 -> OpenAPI/Swagger를 선택합니다. 이전에 내보낸 .yaml 또는 .json 파일을 업로드합니다. 공개적으로 접근 가능한 소스 파일 URL이 있다면, URL을 통해서도 가져올 수 있습니다.
업로드 후, Apidog은 API 문서를 자동으로 구문 분석하여 가져오고, 미리 보기 인터페이스에서 이를 추가로 수정하고 관리할 수 있습니다.
방법 2: 온라인 링크를 통한 예약된 가져오기
Swagger API 문서가 자주 업데이트되는 경우 수동으로 내보내고 가져오는 작업이 번거로울 수 있습니다. 이 경우, Apidog의 예약된 가져오기 기능을 사용하여 Swagger 문서를 자동으로 동기화할 수 있습니다. 아래는 단계별 설명입니다:
1단계. 온라인 링크 확보
Swagger 문서가 공개 URL을 통해 액세스 가능해야 합니다.
https://petstore.swagger.io/v2/swagger.json2단계. OpenAPI 문서 가져오기를 위한 예약된 작업 설정
Apidog에서 예약된 가져오기를 설정할 프로젝트로 이동한 후, 프로젝트 설정 -> 데이터 가져오기 -> 예약된 가져오기를 선택하고 새 작업을 생성합니다. 온라인 Swagger 문서 URL(데이터 소스 URL)을 입력하고 가져오기 간격(예: 3시간마다, 12시간마다 등)을 설정합니다.
방법 3: IDEA 플러그인을 통한 원클릭 업로드
Apidog IDEA 플러그인은 로컬 Java 및 Kotlin 프로젝트 소스 코드를 인식하고, 자동으로 API 문서를 생성하여 Apidog 프로젝트에 동기화합니다. Spring Boot와 같은 일반적인 프레임워크를 지원하여 실제로 코드에 영향을 주지 않는 경험을 제공합니다.
마이그레이션 프로세스를 더 효율적으로 만들기 위해, IDEA 플러그인을 사용하는 단계는 다음과 같습니다:
1단계. Apidog IDEA 플러그인 설치
IntelliJ IDEA(버전 2019.3 이상)를 열고, 설정 -> 플러그인으로 이동한 후 "Apidog Helper"를 검색하여 설치합니다. 설치 후 IDEA를 재시작합니다.
2단계. API 액세스 토큰 구성
Apidog에서 오른쪽 상단에 있는 프로필 사진을 클릭하고 계정 설정 -> API 액세스 토큰을 선택합니다. 여기에서 API 액세스 토큰을 생성하고 필요에 따라 유효 기간을 설정합니다.
IDEA에서 "Apidog Helper" 플러그인 설정을 열고 API 액세스 토큰을 입력한 후 “Test Token”을 클릭합니다. 성공하면 “Apply” 또는 “OK”를 클릭하여 설정을 저장합니다.
3단계. API 동기화
프로젝트 디렉터리 트리에서 모듈 노드를 마우스 오른쪽 버튼으로 클릭하고 "Apidog에 업로드"를 선택하여 모듈 내 모든 인터페이스를 동기화합니다. 또는 Controller 파일을 열고 마우스 오른쪽 버튼을 클릭한 후 "Apidog에 업로드"를 선택하여 Controller 내 모든 인터페이스를 동기화할 수 있습니다.
첫 번째 동기화 시, 구성 대화 상자가 표시되어 관련 팀과 프로젝트를 선택하게 됩니다. 기본적으로 인터페이스는 프로젝트의 루트 디렉터리에 업로드됩니다.
4단계. API 문서 보기
동기화가 성공적으로 완료되면, Apidog을 열어 자동으로 생성된 API 문서를 확인할 수 있습니다.
방법 4: Open API를 통한 가져오기
Apidog은 개발자가 Swagger/OpenAPI 형식의 API 데이터를 API를 통해 직접 가져올 수 있는 Open API를 제공합니다. Open API 문서는 https://openapi.apidog.io/에서 확인할 수 있습니다.
Open API를 통한 가져오기 단계는 다음과 같습니다:
1단계. API 액세스 토큰 얻기
Apidog에서 오른쪽 상단의 프로필 사진을 클릭하고 계정 설정 -> API 액세스 토큰을 선택하여 인증을 위한 API 액세스 토큰(access_token)을 생성합니다. 필요한 경우 토큰의 유효 기간을 조정합니다.
2단계. 프로젝트 ID 얻기
Apidog에서 프로젝트 설정 -> 기본 설정으로 이동하여 프로젝트 ID를 확인합니다. 프로젝트 ID는 각 프로젝트에 대한 고유 식별자이며, API를 호출할 때 데이터가 올바른 프로젝트로 가져와지도록 하기 위해 필요합니다.
3단계. Open API 호출
OpenAPI/Swagger 형식 데이터를 Apidog에 가져오기 위해 다음 엔드포인트를 호출할 수 있습니다: https://api.apidog.com
경로 매개변수
| 매개변수 이름 | 매개변수 유형 | 필수 | 설명 |
|---|---|---|---|
| projectId | String | 필수 | 데이터 가져올 대상 프로젝트를 지정하는 프로젝트 ID입니다. |
| 예시: | https://api.apidog.com/v1/projects/3760990/import-openapi |
본문 매개변수
| 매개변수 이름 | 매개변수 유형 | 필수 | 설명 |
|---|---|---|---|
| input | String/Object | 필수 | 가져올 OpenAPI/Swagger 데이터로, JSON/YAML 문자열 또는 객체로 감싸진 URL을 사용할 수 있습니다. |
| options | Object | 선택 | 대상 디렉터리 ID 설정, 인터페이스 덮어쓰기 동작 등의 고급 옵션. 관련 매개변수는 Apidog Open API 문서에서 자세히 볼 수 있습니다. |
요청 본문 예시:
{
"input": {
"url": "https://petstore.swagger.io/v2/swagger.json"
},
"options": {
"endpointOverwriteBehavior": "CREATE_NEW",
"endpointCaseOverwriteBehavior": "CREATE_NEW",
"updateFolderOfChangedEndpoint": false
}
}참고:
input매개변수의 값은 문자열 또는 객체일 수 있습니다.
만약 OpenAPI 데이터 문자열을 직접 제공하려면, 다음 형식으로 전달할 수 있습니다. 이 문자열은 JSON, YAML 또는 X-YAML 형식일 수 있습니다:
{
"input": "{'openapi':'3.0.0','info':{'title':'Sample API','version':'1.0.0'},'paths':{'/sample':{'get':{'summary':'Sample endpoint','responses':{'200':{'description':'successful operation'}}}}}}"
}만약 OpenAPI/Swagger 형식 데이터의 공개 URL을 제공하려면, 다음과 같은 형식으로 전달할 수 있습니다:
{
"input": {
"url": "https://petstore.swagger.io/v2/swagger.json"
}
}데이터 소스가 인증을 요구하는 경우, 인증을 위한 Basic Auth 정보를 제공할 수도 있습니다:
{
"input": {
"url": "https://petstore.swagger.io/v2/swagger.json",
"basicAuth": {
"username": "apiUser",
"password": "securePassword123"
}
}
}헤더 매개변수
위에서 언급된 필수 매개변수 외에도 요청 헤더에 관련된 인증 정보를 포함해야 합니다. 다음은 해당 예시입니다:
| 매개변수 이름 | 매개변수 유형 | 필수 여부 | 설명 |
|---|---|---|---|
| X-Apidog-Api-Version | String | 필수 | Open API 버전 번호; 현재 지원되는 버전은 2024-03-28입니다. |
| Authorization | String | 필수 | 인증 형식; 첫 번째 단계에서 얻은 개인 액세스 토큰을 포함한 Bearer 방식 사용. |
예시:
'X-Apidog-Api-Version': '2024-03-28'
'Authorization': 'Bearer APS-OVWel6j5103zaaaaaaQle99fGNBw8ucH'응답 예시
API 호출이 성공하면, 가져오기 과정에서 생성된, 업데이트된, 무시된 인터페이스 수와 생성 및 업데이트된 데이터 모델 수 등을 포함한 JSON 응답이 반환됩니다. 오류 메시지가 반환되면 필수 매개변수가 누락되었거나 가져온 데이터 형식이 올바르지 않은지 확인해야 합니다.
{
"data": {
"counters": {
"endpointCreated": 20,
"endpointUpdated": 0,
"endpointIgnored": 0,
"endpointFailed": 0,
"endpointFolderCreated": 3,
"endpointFolderUpdated": 0,
"endpointFolderIgnored": 0,
"endpointFolderFailed": 0,
"schemaCreated": 0,
"schemaUpdated": 7,
"schemaIgnored": 0,
"schemaFailed": 0,
"schemaFolderCreated": 0,
"schemaFolderUpdated": 0,
"schemaFolderIgnored": 0,
"schemaFolderFailed": 0
}
}
}단계 5. 가져오기 결과 보기
가져오기가 완료된 후, 해당 Apidog 프로젝트에서 생성된 API 문서를 확인할 수 있습니다. 입력 매개변수와 응답 메시지에 대한 자세한 정보는 Apidog Open API 문서를 참조하십시오.
자주 묻는 질문
파일 가져오기 중 오류가 발생하면 어떻게 해야 하나요? .yaml 파일을 가져올 때 파싱 오류가 발생하면, 해당 파일이 OpenAPI 사양을 준수하지 않음을 나타내며 수정이 필요합니다. Swagger Editor에 파일을 업로드하여 오류를 진단할 수 있습니다. 문제를 해결한 후 다시 가져오기를 시도하세요.
결론
위에서 설명한 네 가지 방법을 통해 Swagger로 관리되는 API를 Apidog로 쉽게 마이그레이션할 수 있습니다. 각 방법은 다양한 상황에 적합하며, 필요에 따라 가장 적합한 방법을 선택할 수 있습니다. 수동 가져오기, 예약된 온라인 동기화, 플러그인 업로드 또는 Open API 통합을 통해 Apidog는 효율적이고 편리한 API 관리 경험을 제공합니다.
