API와 함께 작업하는 개발자라면, 엔드포인트를 테스트하고 문서화하는 데 인기 있는 도구인 Postman에 익숙할 것입니다. 하지만 OpenAPI 3.0과 같은 표준 형식으로 API 문서를 공유하는 문제에 대해서는 막막할 수 있습니다.
걱정하지 마세요! 이 포괄적인 가이드는 인기 있는 postman-to-openapi npm 패키지를 중심으로 Postman 컬렉션을 OpenAPI 3.0 사양으로 변환하는 과정을 안내해 드릴 것입니다.
Postman을 OpenAPI로 변환하는 이유는 무엇인가요?
시작하기 전에, Postman 컬렉션을 OpenAPI로 변환하고 싶은 이유를 간단히 살펴보겠습니다:
- 표준화: OpenAPI는 RESTful API를 설명하는 업계 표준으로, 다른 개발자들이 문서를 일관되고 쉽게 이해할 수 있도록 합니다.
- 상호 운용성: 많은 도구와 플랫폼이 OpenAPI를 지원하여 다른 시스템 및 서비스와의 통합을 쉽게 만들어줍니다.
- 문서화: OpenAPI는 API 문서화를 위해 명확하고 인간이 읽을 수 있는 형식을 제공하여 다른 사람들이 API를 이해하고 사용할 수 있도록 합니다.
- 코드 생성: OpenAPI 사양을 사용하여 클라이언트 라이브러리와 서버 스텁을 생성할 수 있어 개발 프로세스를 간소화할 수 있습니다.
이제 이 변환을 진행하는 방법을 살펴보겠습니다!
postman-to-openapi 사용: 단계별 가이드
postman-to-openapi npm 패키지는 Postman 컬렉션을 OpenAPI 3.0 사양으로 변환하는 강력한 도구입니다. 이 도구를 사용하는 방법에 대한 단계별 가이드는 다음과 같습니다:
1단계: npm을 통해 postman-to-openai 패키지 설치
먼저, 패키지를 설치해야 합니다. 터미널을 열고 다음 명령어를 실행하세요:
npm install postman-to-openapi
또는 yarn을 선호하신다면:
yarn add postman-to-openapi
2단계: Node.js에서 postman-to-openai 사용
설치가 완료되면 Node.js 프로젝트에서 패키지를 사용할 수 있습니다. 다음은 간단한 예입니다:
const postmanToOpenApi = require('postman-to-openapi')
const postmanCollection = './path/to/your/collection.json'
const outputFile = './output/openapi.yml'
async function convertCollection() {
try {
const result = await postmanToOpenApi(postmanCollection, outputFile, {
defaultTag: 'General'
})
console.log(`OpenAPI 사양: ${result}`)
} catch (err) {
console.error('변환 실패:', err)
}
}
convertCollection()
이 스크립트는 Postman 컬렉션을 OpenAPI 3.0 YAML 파일로 변환합니다.
3단계: postman-to-openai의 사용자 정의 사용법
postman-to-openapi 패키지는 변환을 사용자 정의할 수 있는 여러 가지 옵션을 제공합니다. 유용한 옵션은 다음과 같습니다:
defaultTag: 모든 작업에 대한 기본 태그를 설정합니다 (기본값: 'default').outputFormat: 'yaml' 또는 'json' 중에서 선택합니다 (기본값: 'yaml').includeAuthInfoInExample: 예제에 인증 정보를 포함합니다 (기본값: false).
이 옵션들을 사용하도록 스크립트를 수정해 보겠습니다:
const postmanToOpenApi = require('postman-to-openapi')
const postmanCollection = './path/to/your/collection.json'
const outputFile = './output/openapi.json'
async function convertCollection() {
try {
const result = await postmanToOpenApi(postmanCollection, outputFile, {
defaultTag: 'MyAPI',
outputFormat: 'json',
includeAuthInfoInExample: true
})
console.log(`OpenAPI 사양: ${result}`)
} catch (err) {
console.error('변환 실패:', err)
}
}
convertCollection()
이 스크립트는 인증 정보가 포함된 예제를 JSON 파일로 출력하고 모든 작업을 'MyAPI'로 태그합니다.
만약 postman-to-openai 패키지를 사용하고 싶지 않다면?
postman-to-openapi 패키지는 간편한 변환에 적합하지만, 때로는 더 많은 제어가 필요하거나 특정 요구 사항이 있을 수 있습니다. 몇 가지 고급 기술을 살펴보겠습니다.
옵션 1. APIDog을 사용하여 Postman을 OpenAPI로 변환
APIDog은 Postman 컬렉션을 OpenAPI 형식으로 변환하는 데 도움을 줄 수 있는 또 다른 훌륭한 도구입니다. 사용 방법은 다음과 같습니다:
- APIDog에 로그인하고 "설정" 메뉴로 이동합니다.
- 옵션에서 "가져오기"를 선택합니다.
- 가져오고자 하는 Postman 컬렉션 파일을 선택합니다. APIDog은 컬렉션을 가져오고 변환하여 결과 API 문서를 보고 편집할 수 있도록 합니다.
4. 데이터 내보내기 버튼을 클릭하고 OpenAPI 3.0 형식으로 내보내기를 선택합니다.
하지만 기다려보세요, APIDog는 단지 Postman 컬렉션을 OpenAPI 형식으로 변환하는 도구가 아닙니다. Postman Enterprise에 대한 비용을 걱정하지 않도록 해주는 사용하기 쉬운 대안입니다.
APIDog는 API 테스트 및 모의 서버와 같은 추가 기능을 제공하여 API 개발 및 문서화를 위한 포괄적인 솔루션이 됩니다. 다음은 Postman에 대해 월 $19에 구독하는 대신 APIDog에서 얻을 수 있는 내용입니다:
- 무제한 API 생성
- 플로우 제한 없음 및 무제한 컬렉션 러너 실행
- 무제한 API 호출
- 무제한 API 모의 서버 호출
이 모든 것이 APIDog 무료 버전에서 제공됩니다!
또한 단 $9/월에 Postman 프로페셔널 계획의 모든 기능에 접근할 수 있으며, 이는 $39/월에 해당하는 것입니다!
옵션 2. Postman API를 사용하여 변환하기
Postman 자체에서는 컬렉션을 OpenAPI 형식으로 변환할 수 있는 API를 제공합니다. 사용하는 방법은 다음과 같습니다:
- 계정 설정에서 Postman API 키를 가져옵니다.
- 다음 curl 명령을 사용하세요 (자리 표시자를 실제 값으로 교체):
curl --location --request GET 'https://api.getpostman.com/collections/{{collectionId}}/transformations' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{postman-api-key}}'
- 응답에는 OpenAPI 사양이 포함됩니다. 이를 파일에 저장하여 추후 사용할 수 있습니다.
옵션 3. Postman에서 OpenAPI로 변환하기 위한 온라인 도구
신속하고 코드 없는 솔루션을 선호한다면, 몇 가지 온라인 도구를 사용하여 신속하게 변환할 수 있습니다. 사용하는 방법은 다음과 같습니다:
- 무료 온라인 도구 중 하나를 선택합니다.
- Postman 컬렉션 JSON 파일을 업로드하거나 컬렉션 URL을 붙여넣습니다.
- "변환" 버튼을 클릭하고 결과 OpenAPI 사양을 다운로드합니다.
이 방법은 일회성 변환에 적합하거나 개발 환경을 설정하고 싶지 않을 때 유용합니다.
Postman을 OpenAPI로 번거로움 없이 변환하는 방법: 팁과 모범 사례
최고의 도구를 사용하더라도 몇 가지 문제가 발생할 수 있습니다. 다음은 몇 가지 일반적인 문제 및 해결책입니다:
- 컬렉션 분리: 대규모 컬렉션을 더 작고 관리 가능한 부품으로 나누세요. 이 방법은 변환 후 OpenAPI 사양의 유지 관리를 용이하게 합니다.
- 폴더 사용: 논리적인 구조를 만들기 위해 Postman 컬렉션을 폴더로 조직하세요. 이는 잘 구성된 OpenAPI 사양을 생성하는 데 도움이 됩니다.
- API 변환기: 대규모 Postman 컬렉션을 처리하고 OpenAPI 사양으로 효율적으로 변환할 수 있는 API 변환기와 같은 도구를 활용하세요.
- OpenAPI 검증: 변환 후 OpenAPI 사양을 검증하여 올바르고 완전한지 확인하세요. 이 단계는 변환 과정에서 발생할 수 있는 문제를 식별하는 데 중요합니다.
따라서 매끄러운 변환 프로세스를 보장하기 위해 다음 팁을 기억하세요:
- Postman 컬렉션 정리: 변환 전에 컬렉션의 불일치나 불필요한 요소를 검토하세요.
- 설명적인 이름 사용: Postman에서 엔드포인트, 매개변수 및 응답에 대해 명확하고 설명적인 이름을 사용하세요.
- 예제 포함: OpenAPI 문서를 풍부하게 하기 위해 Postman에 예제 응답을 추가하세요.
- 폴더로 조직: Postman에서 소규모 그룹으로 엔드포인트를 정리하여 OpenAPI에서 태그로 변환되도록 하세요.
- 출력 검증: 변환 후 OpenAPI 검증기를 사용하여 결과 사양이 유효한지 확인하세요.
결론
Postman 컬렉션을 OpenAPI 사양으로 변환하는 것은 API 문서를 표준화하고 다른 시스템과의 통합을 보장하는 데 중요한 단계입니다.
이 가이드에서 설명한 단계를 따르면 Postman 컬렉션을 효율적으로 변환하고 OpenAPI에서 제공하는 이점을 누릴 수 있습니다.
자주 묻는 질문 (FAQs)
Q: Postman 컬렉션을 OpenAPI 사양으로 변환하는 주된 이점은 무엇인가요?
A: 주된 이점은 표준화로, 이를 통해 다른 시스템 및 도구와의 통합이 용이해집니다.
Q: Postman에서 OpenAPI로 변환하기 위해 온라인 도구를 사용할 수 있나요?
A: 예, p2o.defcon007.com 및 APIDog와 같은 온라인 도구를 사용할 수 있습니다.
Q: 대규모 Postman 컬렉션을 변환할 때 어떻게 처리하나요?
A: 대규모 컬렉션은 더 작고 관리 가능한 부분으로 나누거나 폴더를 사용하여 조직하거나 API 변환기와 같은 도구로 변환할 수 있습니다.
Q: 변환 후 OpenAPI 사양을 검증하는 것이 필요한가요?
A: 예, 변환 후 OpenAPI 사양을 검증하는 것은 올바르고 완전한지 확인하는 데 매우 중요합니다.
