API Specification
서론
API를 명세하기 위한 대표적인 API 명세서(Specification)들에 대해 알아보자.
OpenAPI Specification (OAS)
Wordnik이 개발한 OpenAPI Specification(이하 OpenAPI)는 RESTful API를 명세하기 위한 대표적인 API 명세서이다.
과거 2.X 버전까지는 Swagger 2.X로 불렸지만, 3.X 버전부터 OpenAPI Initiative에서 관리하기 시작하면서 OpenAPI 3.X로 명칭이 변경되었다. 현재 Swagger는 OpenAPI를 편집, 문서화, 테스트하기 위한 다양한 도구를 지칭하는 용어로 사용된다.
OpenAPI는 API를 명세하기 위해 JSON 혹은 YAML 포맷을 사용한다.
openapi: 3.0.0
info:
title: Sample API
description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
version: 0.1.9
servers:
- url: http://api.example.com/v1
description: Optional server description, e.g. Main (production) server
- url: http://staging-api.example.com
description: Optional server description, e.g. Internal staging server for testing
paths:
/users:
get:
summary: Returns a list of users.
description: Optional extended description in CommonMark or HTML.
responses:
'200': # status code
description: A JSON array of user names
content:
application/json:
schema:
type: array
items:
type: string
OpenAPI는 확장성이 좋고 다양한 프로그래밍 언어에서 자동 생성 기능을 지원하는 등 다양한 장점을 가지고 있다.
그 중에서도 가장 큰 장점은 사실상 표준에 가까울 정도로 많은 기업과 커뮤니티의 지지를 받고 있다는 것이다. 이에 따라 편집, 테스트, 문서화를 위한 도구 생태계가 매우 뛰어나다.
물론 OpenAPI에게도 단점은 존재한다. 기본적으로 러닝 커브가 높은 편이며 API 규모가 커질수록 명세가 매우 복잡해진다.
또한, HTTP/HTTPS 프로토콜 기반이 아닌 API는 지원이 제한된다. (이는 다른 대부분의 API 명세서도 마찬가지이다.)
현재 OpenAPI의 입지는 다른 API 명세서에 비해 압도적이다.
RAML (RESTful API Modeling Language)
MuleSoft가 개발한 RAML은 RESTful API를 설계하고 개발할 수 있는 모델링 언어이다.
RAML은 API를 명세하기 위해 YAML 포맷을 응용하여 사용한다.
#%RAML 1.0
title: Hello world # required title
/helloworld: # optional resource
get: # HTTP method declaration
responses: # declare a response
200: # HTTP status code
body: # declare content of response
application/json: # media type
type: | # structural definition of a response (schema or type)
{
"title": "Hello world Response",
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
example: | # example of how a response looks
{
"message": "Hello world"
}
RAML은 이미 개발한 API를 명세하는 것보다는 앞으로 개발할 API를 설계하고 공유하기 위한 목적으로 많이 사용된다.
RAML은 OpenAPI와 비교했을 때 읽고 배우기 쉬운 편이지만, 널리 사용되지 않아서 도구와 라이브러리가 부족하다.
API Blueprint
Apiary가 개발한 API Blueprint는 Web API를 명세하기 위해 설계된 언어이다.
API Blueprint는 API를 명세하기 위해 Markdown 포맷을 사용한다.
FORMAT: 1A
# The Simplest API
This is one of the simplest APIs written in the **API Blueprint**. One plain
resource combined with a method and that's it! We will explain what is going on
in the next installment -
[Resource and Actions](02.%20Resource%20and%20Actions.md).
**Note:** As we progress through the examples, do not also forget to view the
[Raw](https://raw.github.com/apiaryio/api-blueprint/master/examples/01.%20Simplest%20API.md)
code to see what is really going on in the API Blueprint, as opposed to just
seeing the output of the Github Markdown parser.
Also please keep in mind that every single example in this course is a **real
API Blueprint** and as such you can **parse** it with the
[API Blueprint parser](https://github.com/apiaryio/drafter) or one of its
[bindings](https://github.com/apiaryio/drafter#bindings).
# GET /message
+ Response 200 (text/plain)
Hello World!
API Blueprint도 RAML과 마찬가지로 앞으로 개발할 API를 설계하고 공유하기 위한 목적으로 많이 사용된다.
API Blueprint는 Markdown 포맷을 사용하기 때문에 학습 곡선이 낮다는 장점이 있다. 또한, Apiary 플랫폼을 통해 API 설계, 테스트 및 문서화 기능을 모두 제공받을 수 있다.
그러나 API Blueprint도 OpenAPI에 비해 도구와 라이브러리가 많이 부족하다는 단점이 있다.
Etc
이외에도 MQTT, WebSocket, Kafka 등의 프로토콜을 지원하는 AsyncAPI Specification이나 Postman에서 사용하는 Postman Collection 등 다양한 API 명세서가 존재한다.
결국 상황에 맞게 API 명세서를 선택하면 된다. 개인적으로는 Source Code -> API Specification -> API Document 과정을 자동화하기 좋은 OpenAPI를 선호한다.