#import

The Design of Web APIs

OAS(Open API Specification)

OAS(OpenAPI Specification)은 REST 명세 포맷으로 널리 사용되고 있는 포맷 중 하나이다.

OAS(OpenAPI Specification)는 프로그래밍 언어에 종속되지 않고 사용하는 REST API 명세 포맷이다.

OAS 포맷은 OAI(OpenAPI Initiative)에서 만들어졌고,

OAS(https://openapis.org)에서 커뮤니티가 주도적으로 만들어가는 명세 포맷이다.

Swagger

Swagger로 명세된 포맷은 2015년 11월 경 OAI로 기증되어,

2016년에 OpenAPI Specification으로 이름이 변경되었다.

API 명세 포맷??

API 명세는 API 세부사항 표현을 위한 데이터 포맷이다.

아래 예시와 같은 텍스트 파일이 API 명세이다.

/gillog:
	description: developer
    get:
    	description: gillog
        content:
          application/json:
            schema:
              properties:
                date:
                  type: date
                  example: 작성일자
                name:
                  type: string
                  example: OAS

위와 같은 설명 포맷을 통해서,

해당 API의 리소스 포함 관계, 동작, RequestBody, Property 등의 정보를 정리된 형태로 보여준다.

API 명세 포맷 사용 이유

워드프로세서, 스프레드시트 등으로도 프로그래밍 인터페이스를 설명할 수 있고, 다른 이들과 공유도 용이하다.

하지만 버전관리, 문서 자동 생성, 문서 코드 생성, 문서 바탕 API 연관 도구 설정 등 ... 의 단점이 존재하고,

API 명세 포맷 사용으로 디자인 단계를 포함해 API LifeCycle 전반적으로 이점을 가질 수 있다.

1. 코드 작성하듯 API를 효율적으로 사용

OAS문서는 단순 텍스트 파일 형태로 Git과 같은 버전 컨트롤 시스템에 쉽게 저장이 가능하다.

이를 통해 API 디자인을 반복하는 동안 간단하게 버전을 지정하고, 수정사항을 추적할 수 있다.

또한 Resource, Action, Parameter, Response 등에 대해 작성하고, 재사용 가능한 컴포넌트(데이터 모델) 정의를 통해서,

프로그래밍 인터페이스를 보다 효율적으로 설명할 수 있게 해주고,

위험하고 고통스러운 API 명세의 Copy & Paste 반복을 피할 수 있게 해준다.

OAS 문서를 작성할 때 사용하고 있는 텍스트 에디터 사용 보다,

OAS 포맷을 위해 만들어진 Swagger Editor[http://editor.swagger.io/]와 같은 온라인 에디터를 사용하는 것을 추천한다.

2. API 명세 및 문서의 손쉬운 공유

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

내부 시스템에서 사용되는 특정 포맷은 소수만 이해할 수 있지만,

OAS 포맷으로 작성된 문서는 널리 통용되어 많은 사람들이 한번에 이해할 수 있다.

또한 OAS문서 양식에 익숙하지 않은 사람들을 위해,

Swagger UI와 같은 Tool로 OAS문서 사용을 위해 사용 가능한 모든 Resource와 Action을 보여주는 API 참조 문서를 생성할 수도 있다.

3. 코드 생성 이상이 가능

API 명세 포맷으로 API를 디자인 했다면,

이 명세 포맷을 바탕으로 일부 구현 코드를 만들거나,

소스 코드 내용 없는 뼈대를 구성하거나,

동작하는 목업을 생성할 수도 있다.

기계도 읽을 수 있는 텍스트 파일 형태의 OAS 명세 포맷을 통해 API 소비 코드를 바로 생성하는 API 명세 장점을 취할 수도 있다.

또한 API 명세 포맷 사용으로 API나 보안 도구 테스트를 수행할 수도 있으며,

이미 개발된 다양한 API 관계 도구 Tool들도 사용할 수 있다.
예를 들어 API Gateway Solution은 OAS 같은 API 명세 파일로 API 제공 프록시에 설정할 수 있다.

YAML(YAML Ain't Markup Language)

OAS 문서는 YAML이나 JSON으로 작성할 수 있는데,

읽고 쓰기 좋은 YAML 포맷으로 작성하는 것이 뜨는 추세이다.

YAML(YAML Ain't Markup Language)은 JSON처럼 사람이 이해하기 쉽게 쓰인 데이터 직렬화 포맷이다.

YAML은 Key, Value 형태의 데이터 포맷으로 아래와 같은 형식이다.

# YAML
simple-property: 1

object-property:
  a-property: a
  b-property: b
  
array-property:
  - item-1-property-1: one
  item-1-property-2: two
  - item-2-property-1: three
  item-2-property-2: four
  
# JSON
{
    "simple-property": "1"
    
    , "object-property": {
        "a-property": "a"
        , "b-property": "b"
    }
    
    ,  "array-of-objects": [
        {
          "item-1-property-1": "one"
          , "item-1-property-2": "two"
        }
        , {
            "item-2-property-1": "three"
            , "item-2-property-2": "four"
          }
    ]
}

YAML 작성 주의사항

• "는 속성과 값에서 허용되지 않는다.

• JSON에서는 {}, ,로 구분하지만,
  YAML에서는 줄바꿈과 들여쓰기로 대체된다.

• JSON 배열에서 쓰던 [], ,는,
  YAML에서는 -와 줄바꿈으로 대체된다.

• 문장 시작에서 #을 통해 주석 처리가 가능하다.