```html
Swagger 에서 Apidog으로 관리되는 API를 마이그레이션하는 데는 여러 방법이 포함됩니다. 이 가이드는 Swagger 파일을 내보내고 Apidog으로 가져오기 위해 4가지 간단한 방법을 설명할 것입니다. 온라인 링크를 사용한 정기적인 가져오기, 원클릭 업로드를 위한 IDEA 플러그인 활용, Open API를 통한 가져오기 방식입니다. 아래는 각 방법에 대한 자세한 단계입니다.
방법 1: Swagger 파일 내보내기 및 Apidog으로 가져오기
이 방법은 가장 간단한 접근법으로, 특히 API 문서가 안정적인 경우 일회성 마이그레이션에 적합합니다. 구체적인 단계는 다음과 같습니다:
단계 1. Swagger 파일 내보내기
Swagger UI에서 API 문서를 .yaml 또는 .json 파일로 내보냅니다. 일반적으로 Swagger UI의 왼쪽 상단 모서리에서 파일을 다운로드할 수 있는 옵션을 찾을 수 있습니다.
인터페이스에 URL 링크가 표시되지 않는 경우, “F12” 또는 “Ctrl+Shift+I”를 눌러 브라우저 콘솔을 열고, 네트워크 -> 가져오기/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.json단계 2. OpenAPI 문서를 가져오기 위한 정기 작업 설정
Apidog에서 정기 가져기를 설정하고자 하는 프로젝트로 이동하여 프로젝트 설정 -> 데이터 가져오기 -> 정기 가져기를 선택하고 새 작업을 생성합니다. 온라인 Swagger 문서 URL(데이터 소스 URL)을 입력하고 가져오기 간격(예: 3시간마다, 12시간마다 등)을 설정합니다.
저장 후 Apidog는 지정된 간격에 따라 최신 API 문서를 자동으로 가져오고 업데이트합니다.
방법 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 액세스 토큰을 입력한 후 “토큰 테스트”를 클릭합니다. 성공하면 “적용” 또는 “확인”을 클릭하여 구성을 저장합니다.
단계 3. API 동기화
프로젝트 디렉토리 트리에서 모듈 노드를 마우스 오른쪽 버튼으로 클릭하고 “Apidog에 업로드”를 선택하여 모듈 내의 모든 인터페이스를 동기화합니다. 또는 컨트롤러 파일을 열고 마우스 오른쪽 버튼을 클릭한 다음 “Apidog에 업로드”를 선택하여 컨트롤러 내의 모든 인터페이스를 동기화합니다.
첫 번째 동기화 시, 관련 팀 및 프로젝트를 선택하도록 구성 대화 상자가 표시되며, 인터페이스는 기본적으로 프로젝트의 루트 디렉토리에 업로드됩니다.
단계 4. API 문서 보기
동기화가 성공하면 Apidog을 열어 자동으로 생성된 API 문서를 볼 수 있습니다.
방법 4: Open API를 통한 가져오기
Apidog은 개발자가 API를 Swagger/OpenAPI 형식으로 직접 가져올 수 있도록 하는 오픈 API를 제공하며, 오픈 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
}
}
inputOpenAPI 데이터 문자열을 직접 제공하는 경우, 다음 형식으로 전달할 수 있습니다. 문자열은 JSON, YAML 또는 X-YAML 형식일 수 있습니다:
{
"input": "{'openapi':'3.0.0','info':{'title':'Sample API','version':'1.0.0'},'paths':{'/sample':{'get':{'summary':'샘플 엔드포인트','responses':{'200':{'description':'성공적인 작업'}}}}}}"
}
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 다음에 1단계에서 얻은 개인 액세스 토큰이 따라야 합니다. |
예시:
'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에 업로드하여 오류를 진단할 수 있습니다. 문제를 해결한 후 다시 가져기를 시도하십시오.
결론
위에서 설명한 4가지 방법을 통해 Swagger에서 관리하는 API를 Apidog으로 쉽게 마이그레이션할 수 있습니다. 각 방법은 다른 시나리오에 적합하므로 필요에 따라 가장 적절한 방법을 선택할 수 있습니다. 수동 가져오기, 정기 온라인 동기화, 플러그인 업로드 또는 Open API 통합을 통해 Apidog는 효율적이고 편리한 API 관리 경험을 제공합니다.
```
