API 문서화 swagger (feat. 아는 만큼 보이는 백엔드 개발)

API 명세서 (API specification)

클라이언트와 서버가 API를 이용해 통신하기위해 어떤 식으로 요청을 보내고 무엇을 응답 데이터로 받을지에 대한 약속을 정리한 문건

 

• URL : 클라이언트가 요청을 보낼 서버 주소 서버에 도메인을 연결하기 전이라 도메인이 없다면 숫자로 된 IP 주소를 작성해도 됨
  • ex) api-dev.inborz.com

 

• API 목차 : 모든 API 목록을 표로 정리, 각 API의 메서드, 하위 URI, API에 대한 설명, 명세서 작성 여부, 서버 반영 여부 등의 정보가 담겨있음 (명세서 작성 자체가 협업을 위한 작업이므로 작성 여부의 내용이 담김) 

  Index	Method	URI	Description	명세서 작성	서버 반영
  1	POST	/app/users	사용자 생성 (회원가입) API	OK	OK
  2	GET	/app/users	전체 사용자 조회 API
  3	GET	/app/users/:userId	특정 사용자 조회 API

   
  • API 세부 명세
    • Method : 클라이언트가 서버에 요청을 보낼 때 사용하는 HTTP 메서드를 작성함
      • POST : 데이터 생성
      • GET : 데이터 조회
      • PUT or PATCH : 데이터 수정
      • DELETE : 데이터 삭제
    • Request (클라이언트가 서버한테)
      • Header : HTTP Header에 담길 데이터를 작성함 예를 들어 JWT와 같은 인증 토큰을 Authorization이라는 이름의 키 값으로 헤더에 담아 전송할 수 있음
      • Body : API 요청 시 클라이언트가 서버로 전송하는 본문 데이터를 작성함 데이터를 조회하거나 삭제할 때는 보내지 않아도 되고, 데이터를 생성하거나 수정할 때만 작성함 (POST, PUT/PATCH) 데이터 형식은 주로 JSON 또는 XML
    • Query String : API 요청 시 URL 뒤에 오는 매개변수 key=value 형식으로 나타냄 각 매개변수는 &로 구분 서버에 특정 조건을 전달하거나 검색 쿼리를 수행하는 데 사용하므로 주로 GET 메서드에서 많이 쓰임
      • 만약 id가 3인 사용자를 조회하는 GET 메서드를 사용하는 API(ex: /app/users?id=3)라면 다음과 같이 작성함 

        Query String	Name	Type	Mandatory	Example	Defalut	Description
        	id	INT	Y	3		사용자 ID

        ※ Mandatory(의무적인) : not null이랑 같은 의미로 보면 될듯
    • Path Variable : API 요청 시 URL 경로 내에 동적으로 변경되는 값을 나타내는 변수 자원의 식별자나 특정 동작을 수행하기 위한 인자로 사용함 변수명을 URL 경로 내에 중괄호({})로 감싸 표현함 
      • 만약 id를 변수로 써서 id번 사용자를 조회하는 GET메서드를 사용하는 API(ex: /app/users/{id})라면 다음과 같이 작성함

        Path Variable	Name	Type	Mandatory	Example	Default	Description
        	id	INT	Y	3		사용자 ID

    • Response Parameters : API 요청에 대한 응답으로 반환되는 데이터의 필드와 속성을 나타냄

      Response Parameters	Name	Type	Mandatory	Example	Default	Description
      	result	Array	Y
      	L id	INT	Y	2		사용자 식별자
      	L name	String	Y	sky		사용자 이름
      	...
      	isSuccess	Boolean	Y	true		요청 성공 여부
      	code	INT	Y	100		응답 코드
      	message	String	Y	사용자 생성 성공		응답 메세지

    • Response Sample : API 요청에 대한 응답 예시, 일반적으로 JSON 형식을 사용함 클라이언트 개발자가 API 응답을 이해하고 처러할 수 있도록 하기위함임

      "isSuccess": true, "code": 100, "message": "사용자 생성 성공" "result" :[     {         "id": 2,         "name": "sky",         "email": "sky@gmail.com",         "password": 987654321,         "admin": "U"     },     {         "id": 19,         "name": "jerry",         "email": "jerry@gmail.com",

    • Result Code : 클라이언트가 보낸 API 요청에 대한 서버의 처리 결과를 나타내는 코드

      Reseult Code	code	message
      	100	사용자 생성 성공
      	200	사용자 생성 실패
      	300	사용자 생성 오류

오픈 API: Swagger

오픈API (OAS, OpenAPI Specification) : REST API를 문서화하기 위한 공개 표준 (open standard), REST API 명세서를 작성하는 포맷을 제공함 

 

Swagger (스웨거) : API 개발자와 프론트엔드 개발자가 원활하게 소통할 수 있도록 API를 개발, 관리, 문서화하는 데 도움을 주는 대표 오픈 API 도구

• 자동으로 API 명세서를 생성하고 Swagger UI를 통해 API 명세서를 시각적으로 구조화해 보여줌
• 프론트엔드 개발자가 실시간으로 업데이트된 API 문서를 확인하고 각 API의 기능, API 요청 시 전달되는 매개변수, 응답 데이터의 형식 등을 쉽게 이해할 수 있음
• API 명세서를 토대로 API 테스트(API 요청을 보내고 응답을 확인)를 할 수 있음
• 클라이언트 개발자가 API를 직접 테스트하고 디버깅할 수 있어 개발 시간이 단축됨