OpenAPI 3.0 Specification Document Cheat Sheet

개요

Swagger의 OpenAPI 3.0 Specification Document를 만들때 사용하는 문법들을 기록합니다.

나중에 빠르게 재사용하기 위해서 기록해두는 목적입니다.

 

api.yaml

openapi: 3.0.3
info:
  title: My Product
  description: |-
    My Product description
  termsOfService: http://swagger.io/terms/
  contact:
    email: bababrll@naver.com
  version: 0.0.1
externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io
servers:
  - url: http://localhost:8080
  - url: https://your-product.dev.com
  - url: https://your-product.beta.com
  - url: https://your-product.com
paths:
  /your-path:
    $ref: 'paths/internal/YourPath.yaml'

path를 정의하고 ref로 달아두면 SRP 관점에서 문서를 조금 더 편하게 관리할 수 있을 것 같습니다.

 

 

YourPath.yaml

parameters:
  - name: jwt
    in: header
    descriptions: jwt 토큰
    required: true
    schema:
      type: string
  - name: phone-number
    in: query
    required: true
    description: 휴대전화번호
    schema:
      type: string
    example:
      01011112222

post:
  tags:
    - yourPathMethod
  summary: 어떤 메서드
  operationId: yourPathMethod
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: '../../requests/YourRequestBody.yaml'  

  responses:
    '200':
      description: 성공
      content:
        application/json:
          schema:
            $ref: '../../schemas/YourMethodResponse.yaml'
    '400':
      description: 필수 요청값이 빠져 있을 수 있습니다.
    '500':
      description: 예측하지 못한 예외를 의마합니다. Backend 에 문의 바랍니다.

 

YourRequestBody.yaml

type: object
required:
  - yourRequestArray
properties:
  yourRequestArray:
    type: array
    items:
      type: string
  list:
    type: array
    items:
      $ref: '../schemas/YourDTO.yaml'

 

YourMethodResponse.yaml

type: object
properties:
  yourColumn1:
    type: string
  yourColumn2:
    type: string

 

YourDTO.yaml

type: object
properties:
  col1:
    type: string
    example: '0000000040095'