API 문서화 공부하기 5 - 매개변수

매개변수 예시 살펴보기

매개변수(Parameter)는 엔드포인트와 함께 전달할 수 있는 옵션이다. 헤더 매개변수, 경로 매개변수 및 쿼리 문자열 매개변수와 같은 여러 유형의 매개변수가 있다. 매개변수의 예시는 다음과 같다. 토스 페이먼츠에서는 문서 옆에 코드 예제를 같이 보여주기 때문에 표를 더 간단하게 작성한 것 같다. Type이나 Required 열을 별도로 두지 않고 parameter name 아래에 같이 작성한 것을 확인할 수 있다. 

출처: 토스페이 API가이드

API문서에서 매개변수들은 대부분 아래 표 형태에서 크게 벗어나지 않는다. 

Parameter	Required/Optional	Description	Data Type
format	Optional	-	String

 

 

문서 작성 시 주의해야 할 사항 

매개변수 유형에 관계없이 각 매개변수에 대해 데이터 형식과 최대값, 최소값을 정의해야 한다. 

매개변수의 데이터 유형
카카오 디벨로퍼 문서에서는 Type 열에서 매개변수의 유형을 명시하고 있다. 토스페이 API가이드에서는 매개변수 명 아래에 Type을 명시해주었다. API가 잘못된 데이터 유형 또는 잘못된 형식인 경우 매개변수를 올바르게 처리하지 못할 수 있으므로 매개변수의 데이터 유형을 작성해줘야 한다. 매개변수의 데이터 유형에는 String, ingterger, bollean, object, array 등이 올 수 있다. 

매개변수의 최대값과 최소값
매개변수는 최대값과 최소값 또는 허용되는 값을 나타내야 한다. 예를 들어 날씨 API가 특정 국가의 경도 및 위도 좌표만 허용하는 경우 문서에 작성되어 있어야 한다. 

그러나 모든 매개변수에 최대값과 최소값이 필요한 것은 아니다. 
- Booleans를 사용하는 경우 true 또는 false이므로 최대 최소값이 필요 없다.
- 열거형을 사용하는 문자열의 경우에는 허용되는 값들을 명시해줄 수 있다. 

즉, 필드에 적용되는 제한을 알아야 하고 제한이 있다면 API문서에 작성해줘야 한다. 

 

 

요청(Request)  문서화하기

아래는 API 문서에서 오른쪽에 Example Request라는 항목이 보인다. 토스페이 API문서에서는 이처럼 가이드 문서에 요청 예시를 같이 보여주고 있다. (나 같은 초보자(?)는 이해하기가 훨씬 수월하다! 직관적으로 보이는 것 같기도 하고!) 아래 요청 예시는 JSON형식이다. JSON은 여러 수준의 중첩이 있는 key(키) : value(값)의 쌍으로 이루어진 데이터 객체로 이루어져 있다. 

출처: 토스페이 API가이드

요청과 응답 모두에서 JSON 데이터를 문서화하는 것은 API문서에서 까다로운 부분 중에 하나라고 한다. 동일한 수준의 몇 개의 키-값 쌍만 객체는 문서화하는 것이 쉽겠지만 객체 안에 여러 객체가 있거나, 다양한 중첩이 있는 경우에는 나타내기가 어렵다. JSON 객체가 100줄 또는 1000줄 이상에 걸쳐 있는 경우도 있다고 하는데 이럴 때는 정보를 표시하는 방법에 대해서 신중하게 생각해야 한다. (이런 정보를 쉽고 간단하게 표현하는 게 IT업계에서 TW가 하는 일이 아닐까?)

아래 이미지는 Swagger Petstore의 예시이다. 여기에서도 단순히 표 형태로 나열하는 것 외에도 토글을 클릭하면 요청 예시를 볼 수 있다. Model 탭을 클릭하면 샘플 요청 본문과 각 요소에 대한 설명도 나타난다. 

출처: Swagger petstore 데모

요청 본문을 문서화할 때 올바른 방법이 정해져 있는 것이 아니다. API의 매개변수를 가장 명확하고 읽기 쉬운 방식으로 설명하는 것이 중요하다고 말한다. 

그럼 다시 실습 예제로 돌아와서 이전 포스팅에 작성했던 예제에 매개변수를 추가해서 다음과 같이 작성해보았다. 위키 페이지를 토대로 작성해보았는데 이게 최선인지는 알 수가 없어서 아쉽다.😂
(units항목은 단위를 입력해야 하니까 string형식이 맞는 걸까? 혹시 누군가 이 포스팅을 보다가 틀린 점이 있다면 댓글로 남겨주세요!)

Surfreport
서핑 높이와 조수 및 바람을 포함한 서핑 조건에 대한 정보를 포함합니다. 이 정보로 서퍼가 서핑을 하기에 적절한 조건인지 알려줄 수 있습니다. 

EndPoint
GET Surfreport/{beachId}
beachId로 특정 해변의 서핑 조건을 가져옵니다. 

Path parameter

Name	Description
{beachId}	해변의 ID값 {beachId}는 사이트의 해변 목록에서 검색됩니다.

Query string parameter

Name	Type	Required	Description
days	Integer	X	응답에 포함할 일 수입니다. 기본값은 3입니다. 최대로 볼 수 있는 일 수는 7입니다.
time	Integer UTC의 Unix형식	X	시간을 포함하면 현재 시간만 응답으로 반환합니다.
units	string	X	측정 단위입니다. metric(야드 파운드 법)과 imperial(미터법) 단위를 사용할 수 있습니다. 값이 없으면 standard 단위가 기본값으로 적용됩니다.

---

요즘 다양한 API문서들을 보다 보면 이런 식으로도 작성할 수 있구나!라는 것을 배워가고 있다.😉 하지만 직접 작성해보는 것은 어렵다..!