손쉽게 Swagger JSON 으로 Postman Collection 만들기

개요

• Postman에서 제공하는 OpenAPI 문서를 활용하면, API 엔드포인트를 일일이 추가하지 않고도 자동으로 Postman Collection을 생성할 수 있음
  
  
• Spring Boot 프로젝트에서 OpenAPI 문서를 기반으로 Postman Collection을 생성하는 방법을 작성
  • 스웨거 설정이 되어있다고 가정
    

    Spring Boot 버전	사용해야 할 springdoc-openapi 버전
    Spring Boot 2.7.x	springdoc-openapi-ui:1.7.0
    Spring Boot 3.x	springdoc-openapi-starter-webmvc-ui:2.0.2

---

OpenAPI 문서 다운로드

1. Swagger UI 접속 > /api/v3/api-docs/approval 클릭
2. http://localhost:8080/v3/api-docs/approval 오른쪽 마우스 클릭 후, 다른 이름으로 저장

📌 포스트맨 호출로도 JSON 파일을 다운받을 수 있습니다!

curl --location 'http://localhost:8080/api/v3/api-docs/approval'

 

Postman API를 사용하여 컬렉션 자동 생성

• Postman API Key 발급하기
  • https://web.postman.co/settings/me/api-keys 접속 후, Generate API Key 클릭

• 생성된 API Key 클립보드에 복사

• Postman API를 사용하여 OpenAPI 문서를 가져와 컬렉션 생성
  
  • cURL을 사용한 컬렉션 자동 생성

curl --location 'https://api.getpostman.com/import/openapi' \
--header 'X-Api-Key: ${발급받은 Postman API Key}' \
--header 'Content-Type: application/json' \
--form 'type="file"' \
--form 'input=@"${파일 경로 위치}"'

Postman Collection  장점

장점	설명
API 문서 자동화	OpenAPI 문서를 기반으로 Postman Collection을 생성하여 API 문서를 최신 상태로 유지 가능
테스트 자동화	Postman에서 컬렉션을 활용하면 API 테스트를 반복 수행할 수 있어 생산성 향상
손쉬운 협업	컬렉션을 팀과 공유하여 테스트 및 개발 진행 가능

참고

• 만약, 스프링 부트 3.x 버전이 아닌  2.7.x 버전을 사용하고 있다면 DTO의 @Schema(example = "...") 값이 Swagger UI 및 OpenAPI JSON에 반영되지 않고 기본 데이터 타입("<string>", "<integer>")으로만 표시되는 문제가 발생 
  
  
• 이를 해결하기 위해서 application.yml 설정 추가

springdoc:
  api-docs:
    enabled: true
    resolve-schema-properties: true // 해당 부분 추가