[ Node.js ] - swagger-ui

swagger

API 관리 도구로써 개발자가 rest api 명세를 쉽게 문서화할 수 있도록 도와주는 도구.

swagger-ui

restapi를 html로 구현하여 보여줌.

swagger-ui 세팅

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

- servers의 url에는 작성된 스웨거 문서를 통해 테스트로 보낼 ip 주소를 적는다. 

- apis는 swagger를 작성한 파일 위치에 대한 정보를 제공하는 곳이다. apis에 작성된 경로를 읽어서 해당 경로에 위치한 파일에 작성된 스웨거 문서를 읽는다.
아래의 코드는 타입스크립트로 작성되어 빌드 후 스웨거 문서가 존재하는 build폴더에 컴파일된 js파일들을 사용하였다.

app.use('스웨거 문서에 접근하기 위한 경로', swaggerUi.serve, swaggerUi.setup(swaggerDoc));

아래의 코드는 localhost:3000/api-docs에 들어가면 작성한 스웨거 문서에 접근할 수 있다.

import express from 'express';
import swaggerUi from 'swagger-ui-express';  // swagger-ui와 익스프레스를 연결해줌
import swaggerJsDoc from 'swagger-jsdoc';   // swagger-ui를 표현해줌

const app = express();

const options = {
    swaggerDefinition: {
        openapi: "3.0.0",
        info: {
            version: "0.0.1",
            title: 'swagger-test',
            description: "swagger test",
            // 접근하는 경로에 대한 정보
        },
        servers: [{
            description:"test 중입니다.",
            url: "http://localhost:3000"
            // url: "https://www.google.com"
        }]
    },
    apis: [
        "build/swagger/models.js",
        "build/api/*.js"
    ]
}

const swaggerDoc = swaggerJsDoc(options);

app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerDoc));

swagger-ui 실제 사용 예시

import {Router} from 'express'

const router = Router();

/**
 * @swagger
 * /api/test/users:
 *   get:
 *    summary: show users
 *    tags: [test]
 * 
 */
router.get('/users',()=>{console.log('test')})

/**
 * @swagger
 * /todos/{id}:
 *   get:
 *    summary: finde user
 *    tags: [test]
 *    parameters:
 *      - name: id
 *        in: path
 *        requires: true
 *        description: the id is the user to return
 *        schema:
 *          type: integer
 *    responses:
 *      200:
 *        description: OK
 *        content:
 *          application/json:
 *             schema:
 *               type: object
 *               properties:
 *                  userId:
 *                    type: integer
 *                  id:
 *                    type: integer
 *                  title:
 *                    type: string
 *                  completed:
 *                    type: boolean
 */
router.get('/user',()=>{console.log('test2')})

/**
 * @swagger
 * /complete/search:
 *   get:
 *     summary: 자동완성 검색 결과를 반환
 *     parameters:
 *       - name: q
 *         in: query
 *         schema:
 *           type: string
 *       - name: client
 *         in: query
 *         scheam:
 *           type: string
 *     responses:
 *       200:
 *        description: A text File
 *        content:
 *           text/plain:
 *             schema:
 *                type: string
 * 
 * 
 */
export default router
// parameters ==> 어떠한 parameter를 보내는가?
// in: path ==> url안에 변수로 설정한 부분에 해당 값이 포함될때 사용
// in: query ==> 파마리터 형태로 어떠한 값은 ~하다라고 명시해줄때 사용
// required ==> 클라이언트가 반드시 해당 id값을 보내야함
// schema:
//    type: integer   ==> 정수형태로 해당 파라미터를 넘기도록  

// reqponse  ==> 응답관련
// application/json  ==> 반환값은 json형태
// properties  ==> 말그래도 반환되는 값의 속성에 대한 정보

출처

https://any-ting.tistory.com/105

[Swagger] Node.js Swagger API 문서화

https://blog.logrocket.com/documenting-your-express-api-with-swagger/