Swagger로 API 명세 작성하는 법 - innovationacademy-kr/slabs-munetic GitHub Wiki

Swagger란?

Swagger(스웨거)는 개발자가 REST API 서비스를 설계, 빌드, 문서화할 수 있도록 하는 툴이다. Swagger는 다음과 같은 경우에 유용하게 사용된다.

다른 개발팀과 협업을 진행할 경우
이미 구축되어있는 프로젝트에 대한 유지보수를 진행할 경우
백엔드의 API를 호출하는 프론트엔드 프로그램을 제작할 경우

기능

API 디자인
API 빌드
API 문서화
API 테스팅
API 표준화

장점

API 정보 현행화 가능
API를 통해 Parameter, 응답 정보, 예제 등 Spec 정보 전달이 용이함
실제 사용되는 Parameter로 테스트 가능

출처 : https://sarc.io/index.php/development/1974-swagger

Swagger yaml/yml 파일 작성법

api 명세를 yaml/yml 파일이나 json 파일로 작성하면 Swagger가 이를 웹문서 형식으로 보여준다. 이 프로젝트에서는 yml 파일 형식으로 작성되었다.

0. VScode extension 설치

OpenAPI(Swagger) : OpenApi 작성에 필요한 IntelliSense, linting, schema enforcement, code navigation, definition links, snippets 등 다양한 기능을 지원합니다.
Swagger Viewer : 작성중인 OpenApi를 Preview 할 수 있는 기능을 지원합니다.

1. api info 작성하기

swagger: '2.0' #swagger or openapi 버전을 지정합니다. 여기서는 swagger 버전을 기준으로 작성하였습니다.
info:
  title: API Title #api의 제목
  version: '1.0' #api 버전
host: 'munetic.42cadet.kr',
basePath: '/api',
tags: # 각 api에 태그를 부여해 관심사별로 api를 분류할 수 있습니다.
  - name: Auth
    description: Authorization
  - name: User
    description: User Information
  - name: Lesson
    description: Lesson Information

2. component 작성하기

component는 반복되는 형태의 req나 res를 모듈화 하는 기능입니다. 작성된 component는 각 api를 작성할 때 참조해 사용할 수 있습니다. 여기선 definitions 이라는 이름으로 component를 구성하였습니다. 생성된 component를 사용하는 방법은 3. 구체적인 api 작성하기에서 안내합니다.

definitions:
  User: # 컴포넌트 이름
    type: object
    required: # 반드시 포함되어야 하는 요소들
      - 'id'
      - 'password'
      - 'type'
    properties: # 컴포넌트를 구성하는 모든 요소들
      id: # 요소 이름
        type: string # 요소 타입
        example: chaeparr # 예시로 특정한 값을 지정할 수 있습니다.
      password:
        type: string
      type:
        enum: # enum 타입은 다음과 같이 정의하거나 ['STUDENT', 'TUTOR'] 처럼 배열로 표현할 수 있습니다.
          - 'STUDENT'
          - 'TUTOR'

3. 구체적인 api 작성하기

paths:
  /auth/signin: #api 경로
    post: #http 요청 종류
      tags: #분류 태그
        - Auth
      summary: Signin User #api 요약
      consumes: #req 데이터 형식
        - application/json
      produces: #res 데이터 형식
        - application/json
      parameters: #파라미터
        - name: body #파라미터 이름
          in: body #위치, 현재 이 정보는 req.body에 담길 예정이기 때문에 body로 지정하였습니다. query, path 등 데이터가 담기는 위치에 따라 다르게 지정합니다.
          required: true #반드시 존재해야하는 파라미터인지에 대한 여부
          schema: #body 형태
            $ref: '#/definitions/User' # definitions에 정의된 User 컴포넌트를 참조하고 있습니다.
      responses:
        '201': #응답 상태 코드
          description: Created User #응답에 대한 설명
          schema: #응답 형태
            type: object
            properties:
              message:
                type: string
                example: 'Success' #응답 속성 또한 예시로 값을 지정할 수 있습니다.
              data:
                $ref: '#/definitions/User' #User 컴포넌트 참조
        '500':
          description: Internal Server Error
          schema:
            type: object
            properties:
              message:
                type: string
                example: 'Internal Server Error'

더 자세한 내용을 적고싶다면 공식문서를 참고하세요.

express 서버와 Swagger 웹서버 연동하기

패키지 설치

npm i swagger-ui-express swagger-jsdoc

swagger info를 담을 ts파일을 따로 생성합니다.

//swagger.ts
//yml작성할 때 적었던 swagger info를 다음의 형태와 같이 작성합니다.
export const options = {
  definition: {
    swagger: '2.0',
    info: {
      title: 'MUNETIC API',
      version: '1.0.0',
    },
    host: 'munetic.42cadet.kr',
    basePath: '/api',
  },
  apis: ['./src/swagger.yml'], //swaggerJsdoc을 이용해 읽을 yaml/yml, json, js, ts파일들을 배열 요소로 지정합니다.
};

app.ts swagger 연동 코드를 추가합니다.

//app.ts
import { options } from './swagger'; //위에 작성한 swagger.ts
import swaggerUi from 'swagger-ui-express';
import swaggerJSDoc from 'swagger-jsdoc';

/**
 * Swagger 연결
 */
const specs = swaggerJSDoc(options);

app.use(
  '/swagger', //express 서버 주소에 이 경로로 이동하면 Swagger api 웹 문서로 연결됩니다.
  swaggerUi.serve,
  swaggerUi.setup(specs, { explorer: true }),
);