API 명세 포맷이란?

API 명세는 API의 세부사항을 표현하기 위한 데이터 포맷입니다. 프로그래밍 인터페이스가 단순한 텍스트 파일 형태로 정리되며, 파일 자체가 데이터를 구조화 해서 포함하고 있으므로 프로그램이 파일을 읽을 수 있고, 다른 무언가로 변환하기도 쉽습니다.

프로그래밍 인터페이스에서 데이터를 정확하게 설명하고자 할 때 API 명세 포맷을 이용하면 더 효율적이고 간단합니다. 특히 프로젝트와 관련된 모든 사람들과 디자인을 공유할 때 좋습니다.

대표적인 API 명세 포맷으로는 OAS가 있습니다.

OAS

OAS(OpenAPI Specification)는 프로그래밍 언어에 상관없이 사용하는 REST API 명세 포맷입니다.

OAS문서는 다른팀이나 회사 같은 타인에게 디자인에 대해서 공유하고 피드백을 받기 쉬운 수단입니다.

기본 OAS 문서는 API 이름이나 버전같은 일반적인 정보를 제공하며, 이 문서는 가용한 리소스와 리소스들의 가능한 HTTP 메서드로 식별된 동작들, 그리고 파라미터와 리스폰스를 묘사합니다.

코드숨 공부방 예약하기로 예를들어 보겠습니다. 코드숨 공부방 좌석 예약하기를 리소스, 액션, 파라미터, 반환값으로 나누어보면

  • 리소스: 좌석
  • 액션: 좌석 예약 생성
  • 파라미터: 좌석 번호
  • 반환값: 예약 내역 정보

와 같습니다. 그리고 이것을 OAS 문서로 표현해보면 아래와 같습니다.

openapi : "3.0.0"

info:
  title: reservations API
  version: "1.0"

paths:
  # 리소스: 좌석
  /seats/{seatId}:
    description: 좌석을 예약한다.

    # 액션: 좌석 생성
    post:
      summary: 좌석예약 생성
      # 파라미터: 좌석 번호
      parameters:
        - name: seatId
          in: path
          required: true
          description: 예약할 좌석
      # 반환값: 예약 내역 정보
      responses:
        "200":
          description: 예약 내역 정보를 응답합니다.
          content: 
            application/json:
              schema:
                type: object
                items:
                  properties:
                    id:
                      type: number
                    status:
                      type: string

왜 API 명세 포맷을 사용해야 하는가?

API 명세 포맷은 다음과 같은 장점들을 가집니다.

API 코드를 작성하듯 효율적으로 쓸 수 있습니다.

OAS 문서는 프로그래밍 인터페이스를 보다 효율적으로 설명할 수 있도록 도와줍니다. 리소스, 동작, 파라미터, 리스폰스나 재사용 가능한 컴포넌트 모델을 정의할 수 있습니다. 이는 API 명세의 복사 붙여넣기의 반복을 피하기 위함입니다.

OAS 문서를 작성할 때에는 스웨거 에디터(Swagger Editor)와 같이 OAS 포맷을 다루기 위해 만들어진 에디터를 사용하는 것이 좋습니다. 이런 도구들은 코드를 작성할 필요 없이 OAS 문서를 생성할 수 있도록 도와줍니다.

버전 관리를 쉽게 할 수 있습니다.

OAS문서는 단순한 텍스트 파일로 코드처럼 Git 같은 버전 컨트롤 시스템에 쉽게 저장할 수 있습니다. 간단하게 버전을 지정하고 수정 사항을 추적할 수 있게 됩니다.

코드를 생성 하는 것 이상으로 다양한 것을 할 수 있습니다.

API 명세 포맷으로 API를 표현했다면, 이 명세 포맷을 바탕으로 일부 구현 코드를 만들어낼 수 있습니다. 소스 코드의 내용이 없는 뼈대를 만들거나 , 동작하는 목업을 만들 수도 있습니다. 컨슈머 역시 API를 소비하는 코드가 자동으로 생성되는 경험을 통해 기계가 읽을 수 있는 API 명세의 장점을 취할 수 있습니다. 그리고 API 명세 포맷을 사용하게 될 경우, API나 보안 도구 테스트를 할 수 있으며, 이 외에도 다양한 API와 관련된 도구들을 쓸 수 있습니다. API 게이트웨이 솔루션(보안성 있고 외부에 API를 제공하는 프록시역할)은 OAS 같은 API 명세 파일로 설정할 수 있습니다.

프로그래밍 인터페이스를 보다 효율적으로 설명할 수 있도록 도와줍니다.

리소스, 동작, 파라미터, 리스폰스를 작성할 때, 재사용가능한 컴포넌트를 정의할 수 있습니다. API 명세를 복사 붙여넣기를 하지 않고 보다 효율적으로 재사용할 수 있게 됩니다.

API 명세 포맷을 사용해야 할 때

그렇다면 API 명세 포맷은 언제 사용해야 할까요? API 목표를 식별하고, 목표와 컨셉, 데이터를 프로그래밍 가능한 표현으로 설계할 때 사용해야 합니다. 목표 뒤에 숨어있는 컨셉들을 식별하려고 API 명세 표맷을 사용해서는 안됩니다. 즉 API가 무엇을 제공할지 명확하게 알고 난 뒤 프로그래밍 인터페이스를 디자인해야 하는 것이죠.

OAS를 이용해서 문서화하는 방법

API 명세 포맷은 사람이 읽기 좋은 표현 수단으로 파일을 제공할 수 있는 방법을 제공하는 것을 목표로 해야합니다.

그렇다면 이제 REST API 리소스들과 액션을 OAS를 이용해 문서화해보도록 하겠습니다.

API 목표 캔버스

누가 (API 사용자) 무엇을 (API사용자들이 할 수 있는 것) 어떻게 (무엇을 단계별로) 입력 (각 단계를 진행 하기 위해 요소 나열) 출력 (각 단계의 반환과 그 쓰임새) 목표 (명시적이고 간결하게 각각의 어떻게 + 입력 + 출력을 재구성)
코드숨 멤버 공부방을 예약한다. 주말에 예약 할수있다 날짜, 계획 예약 번호, 이름 날짜, 계획을 입력해서 예약한다. 
openapi: "3.0.0" # OAS 버전
info: # API 일반 정보 
  title: 공부방예약 API
  version : "1.0"
paths: # api의 리소스
  /reservations: # 리소스의 경로
    description: 공부방 예약 # 리소스의 설명
    post: # 액션의 HTTP 메서드
      summary: 예약 추가 # 액션의 짧은 설명
        requestBody: # 바디 파라미터의 정의
        content:
        application/json: # 리퀘스트의 바디의 미디어 타입
        schema: # 바디 파라미터 스키마
          required: true # 공급처의 필수 속성
            - date
            - plan
          parameters:
           date :
            type: string
             plan : 
            type: string
          schema:
            type: string
      description: # 액션의 긴 설명
      responses: # 액션 리스폰스 리스트
      "200": # 200 OK HTTP 상태 리스폰스
        description: # 리스폰스의 설명
        content:
          application/json:
            schema:
              description: 예약 번호
              properties:
                reservationId: #예약 번호
                  type: number
                name: # 예약자 이름
                  type: String

출처