[Node.js] 기존 프로젝트에 Swagger 연동하기

1. express용 swagger 모듈 설치

> npm i swagger-jsdoc swagger-ui-express --save-dev

npm i swagger-jsdoc swagger-ui-express --save-dev

 

2. app.js 수정(api-docs 대신에 다른 걸 써도 됩니다.)

   이러면 세팅 끝.

const { swaggerUi, specs } = require('./modules/swagger');
...
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));

 

※ 추가

- swagger.js 설명

definition: {
    openapi: "오픈 api 버전",
    // 정보
    info: {
      title: '제목',
      version: '버전',
      description: '설명'
    },
    // 주소
    host: "localhost",
    // 기본 root path
    basePath: "/",
    contact: {
      email: "담당자 이메일"
    },
    // 각 api에서 설명을 기록할 때 사용할 constant들을 미리 등록해놓는것
    components: {
      securitySchemes: { // BearerAuth 인 경우
        bearerAuth: {
          type: "http",
          scheme: "bearer"
        }
      }
    },
    schemes: ["http", "https"], // 가능한 통신 방식
    definitions:  // 모델 정의
    {
      'CommonResponse': {
        type: 'object',
        required: [			// 필수 필드 설정
          "code",
          "message"
        ],
        properties: {
          "code": {
            type: "string",
            description: "결과코드"
          },
          "message": {
            type: "string",
            description: "개발용 메시지"
          }
        }
      }
    }
  },
  apis: ['./routes/*.js'] // api 파일 위치들(경로 수정 가능)

- 각 API별 작성 예시

/**
 * @swagger
 * tags:
 *   name: user
 *   description: User API
 */
 // 이 위는 묶는 용도입니다.(예를 들면 user관련 api를 묶겠다 이럴 때 쓰시면 됩니다.)
 

/**
 * @swagger
 * /users/{id}:					// 경로
 *   get:						// method
 *     summary: 유저 회원가입하기
 *     tags: [user]				// 위에꺼와 동일해야함
 *     security:
 *       - bearerAuth: []
 *     parameters:				// 헤더, path, query 파라미터 정의
 *       - in: header			// 헤더(path parameter는 path, query parameter는 query)
 *         name: os				// 헤더 필드명
 *         schema:				// 형식
 *           type: string
 *           default: aos		// 기본값
 *         required: true		// 필수여부
 *         description : 클라이언트 OS(aos, ios)
 *     requestBody:				// Body 파라미터 정의
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               userId:
 *                 type: integer
 *                 format: int32
 *                 description : 설명
 *     responses:
 *       201:
 *         description: "성공"
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 user:
 *                   $ref: "#/definitions/User"		//(만약 정의된 스키마가 있는 경우)
 *       401:
 *         description: "토큰 갱신 필요"
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 code:
 *                   type: string
 *                   description: 결과코드
 *                   example: "9998"
 *                 message:
 *                   type: string
 *                   description: 디버그 메시지
 *                   example: "Token is expired."
 *       409:
 *         description: "충돌"
 *         content:
 *           application/json:
 *             schema:						// 중복되는 건 스키마로 뺄 수 있음
 *               type: object
 *               properties:
 *                 code:
 *                   type: string
 *                   description: 결과코드
 *                 message:
 *                   type: string
 *                   description: 디버그 메시지
 *             examples:
 *               에러1:
 *                 value:
 *                   code: "1001"
 *                   message: "에러1"
 *               에러2:
 *                 value:
 *                   code: "1002"
 *                   message: "에러2"
 *       500:
 *         description: "서버 에러"
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 code:
 *                   type: string
 *                   description: 결과코드
 *                   example: "9999"
 *                 message:
 *                   type: string
 *                   description: 디버그 메시지
 *                   example: Server Error!
 */

만약 안 된다면 댓글로 질문 받을게요.