Skip to content

Swagger로 API 명세 작성하는 법

Jump to bottom
chaeinP edited this page Dec 18, 2021 · 4 revisions

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. Swagger/Openapi 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'],
};
  • 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 }),
);

Clone this wiki locally