[NodeJS] ExpressJS에서 Swagger 사용하기

💁‍♀️ Swagger 란?

대부분의 프로젝트는 프론트엔드와 백엔드가 나눠진다.

백엔드 개발자는 API를 만들어서 API 사양서를 프론트엔드 개발자에서 전달해줘야한다.

API 사양서를 엑셀이나, 워드로 관리한다면 백엔드 개발자도 프론트엔드 개발자도 서로 번거로워질 것이다.

API가 수정되었다고해도 엑셀이나, 워드에 바로바로 업데이트를 하지않으면 도로묵이기때문이다.

Swagger를 사용하면 REST API 문서화를 도와주고 API를 바로 실행해서 테스트도 가능하니 한번 사용하면 정말 편한 프레임워크다.

🧚‍♀️ ExpressJS에 Swagger 적용하기

본격적으로 Swagger를 적용하기 전에 사전작업이 필요하다.

ExpressJS를 사용해서 개발한 REST API 프로젝트가 있어야한다.

사전 작업해둔 프로젝트가 없다면 아래 링크로 들어가서 프로젝트를 Clone하면 된다.

Joooohee/basic-express

아래 명령어를 입력해서 필요한 패키지를 다운로드한다.

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

swagger-ui-express : API 문서를 위한 UI 렌더링을 위한 패키지

swagger-jsdoc : 주석에 Swagger 태그를 추가하여 API를 문서화하는 패키지

src/app.js에 두 모듈을 추가한다.

import swaggerUi from "swagger-ui-express";
import swaggerJsdoc from "swagger-jsdoc";

 

src폴더 안에 swagger.js파일을 추가하고 Swagger설정에 대한 옵션을 정의한다.

const options = {
    swaggerDefinition: {
        openapi: "3.0.0",
        info: {
            title: "Express Service with Swagger",
            version: "1.0.0",
            description: "a Rest api using swagger and express.",
        },
        servers: [
            {
                url: "http://localhost:4000",
            },
        ],
    },
    apis: [],
};

export default options;

swaggerDefinition 구성요소

• openapi: 우리가 사용하고있는 Open API버전이다.
• info: API에 필요한 정보를 다루며 선택 필드다.
• info.titile: API 제목
• info.version: API 버전
• info.description: API 상세정보
• servers: API에 대한 기본 URL을 정의하며, 배열로 여러 URL을 정의할 수 있다.

 

app.js파일에 정의한 Swagger설정 파일을 import한다.

그 다음, Swagger설정 파일을 담아서 문서사양변수를 생성하고 router를 추가해서 swagger서버를 설정한다.

const specs = swaggerJsdoc(swaggerOptions);
app.use(routes.swagger, swaggerUi.serve, swaggerUi.setup(specs, { explorer: true }));

 

이제, npm start 명령어를 사용해서 프로젝트를 실행한다.

지정한 Router URL로 들어가면 예쁜 Swagger 페이지를 볼수있다.

 

자! 이제 본격적으로 문서화 작업을 하겠다.

먼저, Schema를 문서화하겠다.

src/User.js파일에 @swagger 태그를 추가해서 User의 대한 정보를 정의한다.

/**
 * @swagger
 *  components:
 *    schemas:
 *      User:
 *        type: object
 *        required:
 *          - name
 *          - email
 *        properties:
 *          name:
 *            type: string
 *          email:
 *            type: string
 *            format: email
 *            description: Email for the user, needs to be unique.
 *        example:
 *           name: joohee
 *           email: joohee@email.com
 */

src/swagger.js파일에 apis배열에 model파일들의 경로를 지정한다.

apis: ["./src/models/*.js"]

새로고침을 하면 Schema가 추가된것을 볼수있다.

 

이제 Router을 문서화하겠다.

src/routers/userRouter.js파일에 각각의 라우터의 대한 정보를 정의한다.

/**
 * @swagger
 * tags:
 *   name: Users
 *   description: User management
 */
const userRouter = express.Router();

/**
 * @swagger
 * path:
 *  /user:
 *    get:
 *      summary: Select User
 *      tags: [Users]
 *      responses:
 *        "200":
 *          description: A user schema
 *          content:
 *            application/json:
 *              schema:
 *                $ref: '#/components/schemas/User'
 */
userRouter.get(routes.user, getUser);

/**
 * @swagger
 * path:
 *  /user:
 *    post:
 *      summary: Create a new user
 *      tags: [Users]
 *      requestBody:
 *        required: true
 *        content:
 *          application/json:
 *            schema:
 *              $ref: '#/components/schemas/User'
 *      responses:
 *        "200":
 *          description: A user schema
 *          content:
 *            application/json:
 *              schema:
 *                $ref: '#/components/schemas/User'
 */
userRouter.post(routes.user, postUser);

이번에도, src/swagger.js파일에 apis배열에 router파일들의 경로를 지정한다.

 apis: ["./src/models/*.js", "./src/routers/*.js"]

새로고침을 하면 Router가 추가된 것을 볼수있다.

테스트도 쉽게 가능하다.

 

완성 코드는 swagger-express branch에서 확인할 수 있다.

Joooohee/basic-express

 

참고사항

• Swagger: Time to document that Express API you built!
• Documenting your Express API with Swagger
• How to add Swagger UI to existing Node js and Express.js project

---

🎉  피드백은 언제나 환영입니다. 🎉

---