[Swagger] 작성법 정리 및 예제 실습

 

real-dongsoo7.tistory.com/58

Swagger를 이용해보자! 1편

swagger_test.yaml

0.00MB

Swagger 란?

스웨거(Swagger)는 개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크이다. 대부분의 사용자들은 스웨거 UI 도구를 통해 스웨거를 식별하며 스웨거 툴셋에는 자동화된 문서화, 코드 생성, 테스트 케이스 생성 지원이 포함된다.

 

 

Swagger 작성법

https://editor.swagger.io/ 여기에 접속하면 기본적인 예제가 나온다. 이 곳에서 자신이 작성한 Swagger 문법에는 오류가 없는 지 확인할 수 있고, 예상 되는 결과도 오른쪽 화면에 나오게 된다.

 

.yaml이 지원되는 Swagger의 최상단의 OpenAPI Object로는 openapi, info, servers, paths, components, security, tas, externalDocs 같은 Field로 이루어져 있다. (자세한 설명) 

openapi: 3.0.0
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: 에러 메세지
    RoomLogInfo:
      type: object
      properties:
        idx:
          type: number
          description: roomLog의 인덱스
        name:
          type: string
          description: roomLog의 방 이름
        roomID:
          type: string
          description: 'rest-api 서버 방에 상응하는 roomLog의 방 ID, 실제 방이 없어지면 null'
        ownerID:
          type: string
          description: 방을 만든 사람의 ID 값(hyperAuth 관련)
        startedAt:
          type: number
          description: 방에 리더가 입장한 시각
        endedAt:
          type: number
          description: 방이 만료되거나 방에 모든 참가자가 나간 시각
        hostName:
          type: string
          description: 방을 만든 사람의 이름(최초의 리더)
        terminatesStably:
          type: boolean
          description: 방이 제대로 삭제 되었는지 여부
        transmissionMode:
          type: string
          description: '웨비나 인지, 미팅인지의 여부'
        capacity:
          type: number
          description: 방의 수용 인원
servers:
  - url: '/{basepath}'
    description: '상대 경로 설정, reverse proxy'
    variables:
      basepath:
        default: restapi/v1.1
  - url: /
    description: reverse proxy 없이
info:
  title: REST API TEST
  version: 1.0.
  description: 'Statistics API TEST 입니다'
paths:
  /log/rooms:
    get:
      tags:
        - Statistics
      summary: 기간 내의 방 정보를 가져옴
      parameters:
        - in: query
          name: startDate
          schema:
            type: string
            default: '2020-01-01'
          description: |
            기간 내 검색 기능을 위한 시작일.(00시 기준)

            date type은 ISO 8601 YYYY-mm-dd을 사용함.
          example: '2021-01-01'
          required: false
        - in: query
          name: endDate
          schema:
            type: string
            default: '2050-12-31'
          description: |
            기간 내 검색 기능을 위한 종료일. (24시 기준)

            date type은 ISO 8601 YYYY-mm-dd을 사용함.
          example: '2021-05-10'
          required: false
        - in: query
          name: pagingSize
          schema:
            type: number
            default: 10
          description: |
            Pagination에 필요한 pagingSize 값.

            다른 의미로 한번에 보여주는 값을 갯수를 나타냄.

            또 다른 query string인 pagingIndex과 동시에 사용하거나

            동시에 사용하지 않아야함.
          example: 10
          required: false
        - in: query
          name: pagingIndex
          schema:
            type: number
            default: 1
          description: |
            Pagination에 필요한 pagingIndex 값

            다른 의미로 전체 목록 중 시작 값의 idx를 나타냄

            또 다른 query string인 pagingSize과 동시에 사용하거나

            동시에 사용하지 않아야함.
          example: 1
          required: false
      responses:
        '200':
          description: 요청 성공
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RoomLogInfo'
        '204':
          description: 검색한 항목 없음
        '400':
          description: 요청 실패
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                INVALID_PARAMETER:
                  description: >-
                    request 형식 오류(startDate, endDate, pagingSize, pagingIndex 값
                    오류)
                  value:
                    error: INVALID_PARAMETER
        '500':
          description: 그 외의 에러
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
tags:
  - name: Statistics
    description: |
     통계 기능을 제공합니다.