OpenAPI Specification 3(OAS 3)에 맞게 문서 작성하기

회사에서 REST API 설계를 해야 해서 OSA 3 기준으로 문서를 작성하게 되었습니다.

REST API 구조는 기본적으로 만들 수 있지만, OpenAPI Specification을 따라본 적은 없어서 이번에 처음 OAS3 문서를 작성해봤는데요.

초반에 시간을 투자해서 만들어두면 확실히 좀 더 명확한 소통이 가능한 거로 보입니다.

작성법과 각종 예제는 공식 문서에서도 충분히 제공되고 있기 때문에 공식 문서와 몇 가지 도움이 되는 홈페이지를 소개해드리려 합니다.

공식 문서 보기

역시 가장 좋은 방법은 공식문서 보기겠죠.

OpenAPI Specification - 3.0.1

Example과 사용 할 수 있는 문서 형식들에 대한 정보를 제공합니다.

OAS 3 문서는 YAML과 JSON 포맷을 사용할 수 있습니다.

OpenAPI Specification Visual Documentation


OpenAPI Specification Visual Documentation

공식문서는 대부분 텍스트로 이루어져 있지만, 이 사이트는 좀 더 보기 좋은 모양으로 이루어져 있습니다.

바로 문서 시각화를 제공하는데요. 공식문서에서 찾으면서 스크롤 왔다갔다 하다 보면 매우 혼란스러운 경우가 있는데, 이 페이지는 사용할 수 있는 혹은 정의되어있는 문서형식을 쉽게 구분할 수 있습니다.

Swagger

API 에디터 혹은 코드젠 혹은 API 매뉴얼 자동생성 및 테스트 사이트 생성으로 유명한 Swagger!

Swagger는 OAS 3 관련된 공식 문서도 제공합니다.

이 문서를 추천하는 이유는 기능별로 카테고리가 나뉘어있어 원하는 기능을 사용할 수 있습니다.
그리고 다른 이유로는 공식문서의 작성된 기능들이 Too Much란 느낌이 강합니다.

Swagger와 공식 문서 두 개 다 활용하여 자신이 필요한 정보를 잘 조율해서 문서를 작성하시길 권해드립니다.

Swagger Editor

문서를 만들면 어떻게 볼까요?
YAML 혹은 JSON 문서를 봐야 하는 걸까요?

다행히도 아래 Swagger Editor와 함께 사용하면 쉽게 시각화할 수 있습니다.

Swagger Editor

아래는 공식 문서에서 제공하는 예제입니다.
아래 예제를 복사해서 위 Swagger Editor에 붙여넣기 하면 오른쪽 뷰에서 Swagger가 제공하는 UI를 확인할 수 있습니다.


openapi: 3.0.0
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
servers:
  - url: 'http://petstore.swagger.io/v1'
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: An paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pets'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create a pet
      operationId: createPets
      tags:
        - pets
      responses:
        '201':
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  '/pets/{petId}':
    get:
      summary: Info for a specific pet
      operationId: showPetById
      tags:
        - pets
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pets'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Pet:
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string
    Pets:
      type: array
      items:
        $ref: '#/components/schemas/Pet'
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string

이전 버전의 Swagger 에디터에서는 코드 제네레이터와 여러 기능을 제공하지만 OAS 3을 제공하지 않습니다.

하지먼 저 최신버전의 에디터는 여러 기능들을 제공하지 않는 대신(아직 개발중인 걸로 보입니다) OAS3을 지원하고 UI가 좀더 최신화 되었습니다.

마치며

오랜만에 작성하는 기술 관련 포스트입니다.
지금 회사에서 재미난 걸 많이 시도하기 때문에 공부했던 즉 블로그 소재들이 꽤 있는데
시간이 문제네요!
조만간 다른 포스트로 찾아오겠습니다.

저작자표시