Open API Spefication 활용하기 - 1편 ( Overview )

안녕하세요. 오늘부는 Open API Specification에 대해서 알아보고 Client와 Server의 API를 일치시키는 자동화 과정에 대해서 알아보도록 하겠습니다.

이번 시간에는 기본적으로 OPen API Spescification이란 무엇이며 어떻게 구성되어있으며 어떻게 사용할 수 있을지에 대해서 알아보며, 이후 시간에는 yaml 파일을 분석해보도록 하겠습니다. 그리고 나서 실습으로 OpenAPI Specification Tool을 이용하여 클라이언트 소스를 생성해보기도 하고 서버코드를 기반으로 OpenAPI Specification을 작성해보도기도 하겠습니다.

OpenAPI Specification 이란

OpenAPI Specification은 HTTP API의 인터페이스를 정의하는 문서입니다. 줄여서 OAS라고도 부르는 이것은 특정 언어에 제한되지 않고 모든 언어에서 사용할 수 있는 인터페이스 작성 방법으로 json 또는 yaml을 통해서 정의됩니다. 이렇게 정의된 파일은 Server, 그리고 Client에서 표준으로써 사용할 수 있습니다. 또한 자동으로 생성해주는 라이브러리들도 많이 있습니다.

yaml

yaml 파일로 정의하면 아래와 같은 형식으로 파일을 작성할 수 있습니다. 아래는 GET /api/open 이라는 API를 정의하는 스펙입니다. request 파라미터로는 아무것도 받지 않지만 응답 값으로는 OpenApiResponse를 반환한다는 것을 정의하고 있습니다.

openapi: 3.0.1 # openapi 버전
info:
  title: OpenAPI definition
  version: v0
servers:
- url: http://localhost:8080
  description: Generated server url
paths:
  /api/open/:
    get:
      tags:
      - open-api-controller
      operationId: findResponses
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OpenApiResponse'
components:
  schemas:
    OpenApiResponse:
      type: object
      properties:
        string:
          type: string
        number:
          type: integer
          format: int32
        number2:
          type: integer
          format: int64
        number3:
          type: number
          format: double
        time:
          type: string
          format: date-time

json

아래는 위의 yaml 파일과 동일하지만 형식은 json 형식을 사용하는 방식입니다.

{
  "openapi": "3.0.1",
  "info": {
    "title": "OpenAPI definition",
    "version": "v0"
  },
  "servers": [
    {
      "url": "http://localhost:8081",
      "description": "Generated server url"
    }
  ],
  "paths": {
    "/api/open/": {
      "get": {
        "tags": [
          "open-api-controller"
        ],
        "operationId": "findResponses",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/OpenApiResponse"
                  }
                }
              }
            }
          }
        }
      }
  },
  "components": {
    "schemas": {
      "OpenApiRequest": {
        "type": "object",
        "properties": {
          "string": {
            "type": "string"
          },
          "number": {
            "type": "integer",
            "format": "int32"
          },
          "number2": {
            "type": "integer",
            "format": "int64"
          },
          "number3": {
            "type": "number",
            "format": "double"
          },
          "time": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}

OpenAPI Specification 기반의 API Interface 자동화

OpenAPI Specification을 기반으로한 많은 Tool들이 제공되고 있으며 이를 잘 활용한다면 Open API Specification만을 작성하던지, Server의 코드만을 작성하던지하여 Client에 자동으로 생성된 Client Code를 전달하여 별도의 작업없이 Client에서는 해당 코드를 이용하여 통신이 가능하기도합니다.

이후 실습에서는 Spring Boot의 @RestController 기반의 코드를 작성합니다. 그리고 해당 코드를 기반으로 Open API Specification 파일을 자동으로 만듭니다. 그리고 해당 파일로 Client가 사용할 수 있는 retrofit2 코드를 자동으로 생성하여 통신할 수 있는 실습을 진행해보도록 하겠습니다.

마무리

오늘은 이렇게해서 Open API Specification이 어떤것이고 어떻게 구성되어 있는지 어떻게 자동화를 할 수 있을지에 대해서 알아보는 시간을 가져보았습니다. Open API Specification을 잘 사용한다면 서버와 클라이언틔의 자동화된 API를 공유할 수 있어 생산성에 많은 도움이 될 수 있습니다.

감사합니다.

참조

[1] https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md