OAS(OpenAPI Specification)

in Web

소프트웨어 마에스트로 14기 팀 프로젝트에서 나는 백엔드 파트를 담당하여 Spring Boot를 통한 API 서버 개발을 하게 되었다. 이를 위해 학습 차 게시글을 작성하게 되었다.

정의

  RESTful API를 기정의된 규칙에 맞게 API spec을 json 혹은 yaml로 표현하는 방식을 의미한다. 직접 소스코드나 문서를 보지 않고 서비스를 이해할 수 있다는 장점이 있다.   한 문장으로 정리하면, RESTful API 디자인에 대한 정의(Specification) 표준이다.

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

OpenAPI & Swagger

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

구조

image

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

Version

# 2.0
"swagger": "2.0"

# 3.0
"openapi": "3.0.0"

Multiple Servers

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

# 3.0
"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"
        }
      }
    }
  ]

  2.0에서는 API Endpoint URL을 3가지(host, basePath, schemes)로 정의하였고, 이때문에 하나의 endpoint URL만 정의할 수 있었다. 하지만 3.0에서는 멀티 URL을 지원하게 되면서, 각 URL마다 username, port, basepath를 variables 필드에 가지고 있을 수 있게 되었다.

Components

# 2.0
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
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

  이전 2.0에서는 일부 중복되는 부분이 있어도 그대로 쓸 수 밖에 없었다면,(각 path의 schema 아래부분) 3.0에서는 중복되는 부분을 components로 빼고 path에서는 참조할 수 있게 되었다.

Reference