개요

GDG 챌린지를 진행하며, 멘토님께서 프론트와의 협업을 위해 YAML 파일을 통해 스웨거 문서를 작성해보라고 하심과 동시에 백엔드 코드에 스웨거와 관련된 코드가 들어가지 않도록 하기 위한 방법이 어떤 것이 있을까를 고민해보다가 스웨거 허브에서 작성하면 문제를 해결할 수 있겠다는 생각이 들었다.
개인적으로 알게 된 사용 방법들을 잊지 않기 위해 본 글에 기록해보겠다.

기본 코드

우선 기본적으로 스웨거 허브에서 API 문서를 생성하면 아래 사진과 같다. 이 단계까지는 어렵지 않으니 추가적인 설명은 하지 않겠다.

openapi: 3.0.0 # OPEN API의 버전을 뜻한다.
info:
  version: '1.0' # API 문서의 버전을 뜻한다.
  title: blog # API 문서의 제목을 뜻한다.
  description: blog # API 문서의 설명을 뜻한다.
paths: {} # 각 REST API를 등록하면 된다.

세부 설정

서버 설정

연결할 서버 설정은 다음과 같이 설정할 수 있다.

openapi: 3.0.0
info:
  version: '1.0'
  title: blog
  description: blog API
servers: 
  - url: https://www.sample.com # 자신의 도메인
    description: blog API Server # 자신의 도메인에 대한 설명

JWT 적용

스웨거에 JWT를 적용하려면 다음과 같이 설정할 수 있다.

components:
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT

스키마 컴포넌트화

예외 처리, 요청 DTO 등 여러 요청, 응답 결과는 컴포넌트화 함으로써 재사용할 수 있다. 아래는 DTO 오류 발생 시 응답 할 스키마의 예시이다.

components:
  schemas:
    DTOException: # 이렇게 사용한다.
      description: DTO 오류
      type: object # JSON은 타입이 object이다.
      properties: # JSON의 각 키라고 생각하면 된다.
        success:
          type: boolean
          description: 성공 여부
          example: false # example 값도 넣을 수 있다.
        status:
          type: string
          description: HTTP 상태 코드
          example: NOT_FOUND
        error:
          type: object
          description: 발생한 예외
          properties: # JSON의 키 안에 또 다른 여러 키들을 넣고 싶다면 properties를 넣어주면 된다.
            type:
              type: string
              description: 발생한 예외 종류
              example: MethodArgumentNotValidException
            message:
              type: string
              description: 예외 메시지
              example: DTO 값 오류
          required: # required 설정도 할 수 있다.
            - type
            - message
      required:
        - success
        - status
        - error
# 그리고 사용 시점에서는 $ref: '#/components/schemas/DTOException' 처럼 사용하면 된다.

그 외 작성법

paths:
    /api/comment/{id}:
    post:
      security:
        - JWT: [] # JWT가 필요하다면 작성한다.
      summary: 댓글 작성
      tags: [Comment] # Tag로 각 API가 구분된다.
      parameters: # 파라미터 형식이다.
        - in: path
          name: id
          schema:
            type: integer
          required: true
          description: 스토리 ID
      requestBody: # request body가 필요하면 작성한다.
        content:
          application/json: # application/json 형태를 쓴다.
            schema: # 스키마를 불러올 수 있다.
              $ref: '#/components/schemas/CommentRequest'
      responses:
        '201':
          description: 댓글 생성 완료
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentResponse'
        '400':
          description: DTO 오류
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DTOException'

코드로만 보기에는 잘 모를 수 있으니, 참고할 수 있는 예시 API를 공개해두겠다.
여기를 보면 Swagger hub 문서를 볼 수 있다.

---

부족하거나 보완할 점이 있다면 댓글 부탁드립니다 😃