OpenAPI 란? (feat. Swagger)

Overview

이 문서에서는 API의 기본적인 정의는 알고 있다는 전제하에 OpenAPI와 Swagger의 개념, 차이점, 비교적 최근(2017-07-26) 업데이트한 OpenAPI 3.0에 대해서 알아보도록 하겠습니다.

1. OpenAPI? Open API?

검색창에 OpenAPI라고 치면 수많은 결과가 나옵니다.
근데 의미가 통일되지 않고 중구난방인데요… 그래서 더 헷갈립니다.
저도 이게 대체 무슨 뜻인가 싶었습니다.

그래서 정리하는 정확한 정의!

Open API 는 단어 그대로 “개방된 API”입니다. 즉, 누구나 사용될 수 있도록 API의 endpoint가 개방되어있다면 Open API인것이죠.
예를 들어, 기상청의 단기예보 조회API, 우체국의 우편번호 API 등이 있습니다.
Public API라고도 부릅니다.

OpenAPI 는 의미가 완전 다릅니다.
OpenAPI또는 OpenAPI Specification(OAS)라고 부르는데, 이는 RESTful API를 기 정의된 규칙에 맞게 API spec을 json이나 yaml로 표현하는 방식을 의미합니다.
직접 소스코드나 문서를 보지 않고 서비스를 이해할 수 있다는 장점이 있습니다.

정리하면, RESTful API 디자인에 대한 정의(Specification) 표준이라고 생각하시면 될 것 같습니다.

예전에는 Swagger 2.0와 같은 이름으로 불렸다가 현재는 3.0버전으로 올라오면서 OpenApi 3.0 Specification으로 칭합니다.

한 끗 차이로 의미가 완전 달라지는 OpenAPI… 이제는 절대 안 헷갈릴 듯 합니다.

2. OpenAPI vs Swagger

위에서 언급했듯이, 예전에는 OpenAPI 2.0을 Swagger 2.0으로 불렀었습니다.

그래서 이 둘도 정확한 정의가 필요할 것 같아 정리해둡니다.

참고 (둘이 같은 포스팅 아님):

• What’s the Difference Between Swagger and OpenAPI?
• What Is the Difference Between Swagger and OpenAPI?

Swagger는 2010년대 초 Tam Wordnik이라는 사람이 개발하기 시작했습니다.
처음에는 모든걸 포함하는 방법론이 아니라, Wordnik(회사) 자체 API용 UI로 개발되었고
2015년초에 SmartBear라는 회사에서 Swagger를 인수했습니다.

그리고 2015년 말, SmartBear는 Linux Foundation의 후원으로 OpenAPI Initiative에 Swagger를 기부하면서 OpenAPI Specification으로 이름이 변경되었습니다.

하지만 현재도 여전히 Swagger는 사용되는 용어입니다. 지금은 어떤의미로 쓰이는걸까요?

• OpenAPI : 이전에 Swagger Specification으로 알려진 Specification 자체 (RESTful API 디자인에 대한 정의(Specification))
• Swagger : OpenAPI를 Implement하기 위한 도구 (SmartBear사의 tool)

즉 Swagger는 API들이 갖고 있는 specification을 정의할 수 있는 툴들 중 하나라고 보시면 됩니다.

이런식으로, OpenAPI Specification을 json또는 yaml로 기술한 문서를 swagger-ui를 통해 띄우게되면 브라우저에서 편리하게 API문서를 볼 수 있습니다.

swagger도 여러 도구가 있습니다.
Swagger Editor : 브라우저 기반의 편집기, OpenAPI Spec을 쉽게 작성할 수 있게 도와줌
Swagger UI : OpenAPI spec문서를 브라우저에서 확인할 수 있게 해줌, API Test도 가능
Swagger Codegen : OpenAPI spec에 맞게 Server나 Client의 stub code생성

OpenAPI Specification을 Implement하기위한 Tool들은 Swagger말고도 종류가 굉장히 많은데, 링크(OpenAPI-Specification/IMPLEMENTATIONS.md)를 참조하시기 바랍니다.

3. OpenAPI 2.0 vs OpenAPI 3.0

2015년 Swagger Specification을 OpenAPI Initiative에 기부하면서 OpenAPI Specification(OAS)로 명칭이 바뀌었고, 그 이후 첫번째 major release가 OAS3.0입니다.

2.0때보다 구조가 더 단순해졌고, 재사용성이 증가될 수 있도록 개발되었습니다.

해당 포스팅에서는 3가지 차이점만 소개하겠습니다.
자세한 내용은 -> A Guide to What’s New in OpenAPI 3.0

참고 : Open API spec 2.0 vs 3.0

3.1 Version

2.0에서는 아래와 같이 표기했고,

"swagger": "2.0"

3.0에서는 아래와 같이 표기합니다.

"openapi": "3.0.0"

3.2 Multiple Servers

2.0에서는 API Endpoint URL을 3가지(host, basePath, schemes)로 정의했었습니다.

"host": "petstore.swagger.io",
  "basePath": "/v1",
  "schemes": [
    "http"
  ]

이러한 스펙 하에서는 하나의 endpoint URL만 정의할 수 있었습니다.

3.0에서는 멀티 URL을 지원합니다.

"servers": [
    {
      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
      "description": "The production API server",
      "variables": {
        "username": {
          "default": "demo",
          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
        },
        "port": {
          "enum": [
            "8443",
            "443"
          ],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }
  ]

각 url마다 username, port, basepath를 variables 필드에 갖고있습니다.

3.3 Components

예전에는 일부 중복되는 부분이 있어도 그대로 쓸 수 밖에 없었다면,(각 path의 schema 아래부분)

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      parameters:
        ...
      responses:
        '200':
          description: A single user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    name:
                      type: string

3.0에서는 중복되는 부분을 components로 빼고 path에서는 참조할 수 있게 했습니다.

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      parameters:
        ...
      responses:
        '200':
          description: A single user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

Components에서는 schemas, parameters, responses, examples, security schemes, links, request bodies, headers와 callbacks를 포함하고 있어, 재사용 가능한 모듈로써 사용이 가능합니다.

한줄정리

Open API : 공개된 API
OpenAPI Specification : RESTful API 디자인에 대한 정의(Specification) 표준
Swagger : OpenAPI를 Implement하기 위한 도구

---