API 도구

Postman OpenAPI 변환옮긴 내용과 빠진 내용 확인

컬렉션, 명세 또는 환경 파일을 선택하고 요청 목록과 변환 보고서를 검토한 뒤 결과를 저장하세요.

자동 변환

컬렉션, 명세 또는 환경 입력

{
  "info": {
    "name": "Pet API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://api.example.com"
    }
  ],
  "item": [
    {
      "name": "Pets",
      "item": [
        {
          "name": "List pets",
          "request": {
            "method": "GET",
            "url": "{{baseUrl}}/pets?limit=10",
            "auth": {
              "type": "bearer",
              "bearer": [
                {
                  "key": "token",
                  "value": "demo-token"
                }
              ]
            }
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "pm.test(\"status\", () => pm.response.to.have.status(200));"
                ]
              }
            }
          ]
        },
        {
          "name": "Create pet",
          "request": {
            "method": "POST",
            "url": "{{baseUrl}}/pets",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\"name\":\"Miso\"}"
            }
          },
          "response": [
            {
              "code": 201,
              "status": "Created",
              "body": "{\"id\":7,\"name\":\"Miso\"}"
            }
          ]
        }
      ]
    }
  ]
}

결과

텍스트는 현재 브라우저에서 처리합니다. API 요청, 스크립트 실행, 원격 참조 가져오기는 하지 않습니다.

출력 옵션

변환 모드명세 출력 형식

인식한 자격 증명 마스킹

예시를 기반으로 매핑하며 완전한 계약이 아닙니다. 보고서와 남은 자리표시자를 확인하세요.

500,000자 · 깊이 60 · 노드 50,000개 · 요청 1,000개 · 보고 500개 · 5초.

결과가 오래되었습니다. 다시 검증한 뒤 내보내세요.

복사와 다운로드는 선택한 보기 전체를 내보냅니다. 마스킹은 출력만 변경합니다.

Postman OpenAPI 변환은 실행 가능한 요청 묶음을 API 문서화의 출발점으로 바꿀 때 유용합니다. 요청은 한 번의 호출 예시이고 명세는 허용하는 입력과 응답을 설명하므로, 두 파일에 담긴 정보가 같지는 않습니다.

이미 명세가 있다면 역방향으로 컬렉션을 만들 수 있습니다. 인증 자리표시자나 응답 정의, 스키마 제약은 생성된 요청만으로 복원되지 않으므로 원본 명세를 함께 보관하고 비교하세요.

Postman OpenAPI 변환에서 확인할 수 있는 것

폴더의 요청과 누락 항목을 함께 추적

Postman OpenAPI 변환은 중첩 폴더를 재귀적으로 읽고 폴더 경로를 작업 태그로 남깁니다. 요청 목록은 읽어 들인 호출을, 보고서는 스크립트와 변수 및 지원하지 않는 필드를 보여 줍니다. 같은 경로와 메서드가 중복되면 덮어쓰지 않고 중단합니다.

폴더 속 요청 카드가 명세로 연결되고 스크립트 카드는 경고 쪽으로 분리되는 그림.

환경 설정을 전달하기 전에 값 검토

환경 내보내기와 컬렉션 정리는 기본적으로 자격 증명을 마스킹합니다. 인식한 민감 값은 출력에서 자리표시자로 바뀌고 비활성 환경 항목은 따로 보고됩니다. .env의 줄 수가 줄어든 이유도 확인할 수 있습니다.

환경 변수 행이 설정 파일로 이동하고 비밀 값은 가려지며 비활성 행은 보고서에 남는 그림.

내보내기 전에 정할 세 가지

입력 종류에 맞는 모드 선택

방향을 바꿔도 입력은 그대로 남습니다. 해당 모드의 예제를 불러오거나 맞는 파일을 가져오세요. 컬렉션에는 2.1 스키마 선언이, 환경 파일에는 values 배열이 필요합니다.

검토한 보기의 전체 내용 저장

결과 보기는 변환 파일을, 요청 보기는 전체 목록을, 보고서 보기는 항목 코드와 원본 경로를 내보냅니다. 화면은 50개씩 표시하지만 다운로드에는 선택한 목록 전체가 포함됩니다.

요청과 계약, 환경 설정의 연결

양방향으로 형식 변환

Postman 컬렉션은 OpenAPI 3.0.3으로 변환하며 JSON 또는 OpenAPI YAML 출력을 선택할 수 있습니다. 역방향은 3.0과 3.1을 읽어 Collection 2.1을 만듭니다. 작업 세부 정보에 필요한 로컬 참조는 같은 문서 안에서 해석합니다.

예시를 제약 조건으로 오인하지 않기

쿼리와 헤더 값은 문자열 예시가 되며 JSON 본문은 본문 예시로 남습니다. required나 enum을 임의로 추가하지 않습니다. 역방향은 명시된 example 또는 default를 우선하고, 값이 없으면 이름 있는 자리표시자를 만듭니다.

인증과 서버 선택 기준

Basic, Bearer와 헤더 또는 쿼리의 API Key를 매핑합니다. 역변환에서는 작업, 경로, 루트 순으로 유효한 서버 목록을 찾고 첫 주소를 사용합니다. 여러 후보나 서버 누락, 복잡한 인증 조합은 보고서에 나타납니다.

환경 값을 별도 설정 파일로

Postman 환경 변수는 별도로 내보낸 환경 JSON에서 처리합니다. 활성 스칼라 값은 문자열, null은 빈 값이 됩니다. 공백, 줄바꿈과 달러 기호를 보존하는 인용 방식을 사용하며 잘못된 키나 중복 키는 오류가 됩니다.

자동으로 복원하지 않는 정보

버전 범위: Collection 2.1과 OpenAPI 3.0.x, 3.1.x를 입력으로 받습니다. Swagger 2.0, 다른 Collection 버전 및 OpenAPI 3.2는 지원하지 않습니다. 최신 Postman의 모든 저장 형식을 읽는 도구는 아닙니다.
스크립트와 변수 실행 제외: 사전 요청 스크립트와 테스트를 실행하지 않습니다. 정리 모드에서는 텍스트를 유지하고 변환 시에는 누락을 보고합니다. 동적 변수 평가나 환경, 전역, Vault 값의 자동 통합도 하지 않습니다.
완전한 계약의 왕복 변환은 불가: 역방향은 응답 정의와 검증 제약을 생략하고 보고합니다. 복잡한 매개변수 직렬화, 콜백, webhooks, OAuth 흐름, 서명 및 바이너리 파일 내용은 매핑 범위 밖입니다. 요청 예시가 실제 서비스에서 성공한다고 보장하지 않습니다.
참조와 주소의 경계: 외부 파일이나 원격 참조는 가져오지 않습니다. 로컬 참조 누락과 잘못된 명세는 처리를 중단합니다. 컬렉션 기본 주소를 해석할 수 없으면 /를, 역변환에 서버가 없으면 example.invalid를 사용하고 보고합니다.
마스킹의 한계: 민감한 키 이름, secret 표시 변수, 인증 값, Cookie와 URL 자격 증명을 마스킹합니다. JSON 본문은 구조를 검사하고 다른 본문은 전체를 가립니다. 설명이나 스크립트 속 임의의 비밀은 남을 수 있으므로 출력을 검토하세요. 원본은 수정하지 않습니다.
자원과 입력 제한: 입력 500,000자, 깊이 60, 노드 50,000개, 요청 1,000개, 보고 항목 500개, 결과 묶음 2,000,000자, 작업 시간 5초가 상한입니다. 중복 키, 정밀도가 손실되는 숫자, YAML 별칭과 사용자 태그 및 다중 문서는 거부합니다.

Postman OpenAPI 변환 자주 묻는 질문

YAML과 JSON 명세를 모두 가져올 수 있나요?

OpenAPI에서 컬렉션으로 바꾸는 모드는 둘 다 지원합니다. 컬렉션과 환경 파일 입력은 JSON입니다. 출력 형식 선택은 생성할 OpenAPI 문서에만 적용되며 컬렉션은 JSON, 환경은 .env로 저장합니다.

서로 변환하면 정보가 손실되나요?

네. 실행 절차를 담는 컬렉션과 선언적인 계약은 서로 다릅니다. 보고서를 검토하고 결과를 마이그레이션의 시작점으로 사용하세요. 변환 성공은 인증 성공이나 실제 응답과의 일치를 뜻하지 않습니다.

생성한 컬렉션의 baseUrl은 어떻게 설정하나요?

작업 > 경로 > 루트 순서로 선택한 서버의 첫 URL을 baseUrl 변수에 넣습니다. 뒤의 작업에는 별도 기본 주소 변수를 사용합니다. 서버 변수 기본값을 적용하고 서버가 없으면 example.invalid를 넣어 보고합니다.

비밀 변수가 내보내기 파일에 포함되지 않게 할 수 있나요?

마스킹을 켜 두면 secret 표시나 민감 이름에 해당하는 값을 [REDACTED]로 바꿉니다. 이는 이 도구의 출력만 제어하며 Postman의 내보내기 권한을 변경하지 않습니다. 임의의 텍스트에 숨은 모든 비밀을 식별하지는 못합니다.

컬렉션을 내보낼 때 환경 변수도 함께 포함할 수 있나요?

자동으로 포함하지 않습니다. 환경 JSON을 따로 내보낸 뒤 환경 → .env 모드에 넣으세요. 파일에 담긴 활성 값만 처리하며 빠져 있는 로컬, 전역 또는 Vault 값을 가져오지 않습니다.

예상과 다른 결과가 나왔나요?

작은 요청 묶음부터 확인하세요

Postman OpenAPI 변환으로 작은 컬렉션을 처리하고 요청 목록과 보고서를 원본과 비교하세요. 해결되지 않은 자리표시자를 확인한 뒤 다음 작업에 필요한 파일을 저장할 수 있습니다.

작업 도구로 돌아가기 도구 둘러보기

Postman OpenAPI 변환옮긴 내용과 빠진 내용 확인