포스트맨을 이용한 API 명세서 작성

포스트맨을 이용한 API 명세서 작성

2023. 6. 26. 15:05ㆍ카테고리 없음

Postman을 이용한 API 명세서 작성

Postman은 API 개발, 테스트, 문서화할 수 있게 도와주는 플랫폼입니다. Postman을 이용하여 Kiosk 프로젝트의 API 일부를 만들고 목서버를 생성하여 목 데이터를 테스트해봅니다. 그리고 마지막으로 다른 사람들과 공유하기 위해서 문서화하여 배포하는 것까지 실습합니다.

다운로드 및 설치

다운로드 페이지로 이동하여 포스트맨을 설치합니다.

컬렉션 생성 및 API 생성

Collection 선택 -> Create new collection 버튼 클릭 -> kiosk 컬렉션 생성

API 명세서를 작성하기 위해서 Request를 추가합니다.

추가한 Request의 제목과 URL을 작성합니다.

Mock Server 생성

Postman enables you to create mock servers to assist with API development and testing. A mock server simulates the behavior of a real API server by accepting requests and returning responses. By adding a mock server to your collection and adding examples to your requests, you can simulate the behavior of a real API.

포스트맨을 사용하면 API 개발 및 테스트를 지원하는 모의 서버를 만들 수 있습니다.
모의 서버는 요청을 수락하고 응답을 반환하여 실제 API 서버의 동작을 시뮬레이션합니다.
컬렉션에 모의 서버를 추가하고 Request에 예제를 추가하면 실제 API의 동작을 시뮬레이션할 수 있습니다.

워크스페이스 사이드바 설정에 들어가서 Mock Server를 표시하도록 합니다.

Mock Server 생성 버튼을 클릭합니다.

Mock Server 생성 정보에서 기존 컬렉션으로 만들어둔 kiosk 컬렉션을 선택하여 생성합니다.

Mock Server 이름을 입력하고 생성합니다.

Request 예제 추가

Request의 예제를 추가하고 Mock Server와 이용하여 Request 예제를 추가합니다.

예제를 추가할 Request 선택하고 요청의 예제를 생성합니다.
Mock Server의 URL을 복사합니다.
예제의 URL에 다음과 같이 붙여넣고 끝에 "/products"를 추가하여 URL을 완성합니다.

하단의 Body에 예상되는 결과를 넣습니다.

[
 {
     "categoryName": "COFFEE",
     "categoryId": 1,
     "menus": [
         {
             "menuId": 1,
             "name": "아메리카노",
             "price": 4900,
             "imgUrl": "https://codesquad-project.s3.ap-northeast-2.amazonaws.com/public/img/COFFE/Americano.jpg",
             "hasHot": false,
             "hasIce": true,
             "hasLarge": false,
             "hasSmall": true,
             "categoryId": 1,
             "isBest": true
         },
         {
             "menuId": 2,
             "name": "카라멜 마키아또",
             "price": 5100,
             "imgUrl": "https://codesquad-project.s3.ap-northeast-2.amazonaws.com/public/img/COFFE/CaramelMacchiato.jpg",
             "hasHot": true,
             "hasIce": true,
             "hasLarge": true,
             "hasSmall": true,
             "categoryId": 1,
             "isBest": false
         },
         {
             "menuId": 3,
             "name": "롱블랙",
             "price": 5300,
             "imgUrl": "https://codesquad-project.s3.ap-northeast-2.amazonaws.com/public/img/COFFE/LongBack.jpg",
             "hasHot": false,
             "hasIce": true,
             "hasLarge": false,
             "hasSmall": true,
             "categoryId": 1,
             "isBest": false
         },
         {
             "menuId": 4,
             "name": "프렌치 아메리카노",
             "price": 5500,
             "imgUrl": "https://codesquad-project.s3.ap-northeast-2.amazonaws.com/public/img/COFFE/FrenchAmericano.jpg",
             "hasHot": false,
             "hasIce": true,
             "hasLarge": false,
             "hasSmall": true,
             "categoryId": 1,
             "isBest": false
         },
         {
             "menuId": 5,
             "name": "콜드브루",
             "price": 5700,
             "imgUrl": "https://codesquad-project.s3.ap-northeast-2.amazonaws.com/public/img/COFFE/ColdBrew.jpg",
             "hasHot": false,
             "hasIce": true,
             "hasLarge": true,
             "hasSmall": false,
             "categoryId": 1,
             "isBest": false
         }
     ]
 },
 ...
]

API 문서화

컬렉션에 생성한 API를 문서화하는 실습을 수행합니다.

컬렉션 선택 -> View documentation 선택

오른쪽에 publish를 클릭하여 배포합니다.

배포 성공을 확인합니다.

김용환 블로그