Swagger

swagger... 실제로 스웩이 넘치는 ui로 프론트와 백 사이를 멋지게 연결해주지만, 이게 맞나 싶은 주석 달기... 

autogen 라이브러리도 있는것 같고, ORM과 연결해서 모두 자동화가 될 것 같은데 싶다. 여튼, 

 

설치하고,

npm i -D swagger-jsdoc swagger-ui-express

 

swagger ui를 사용하기 위해 swagger.js파일을 만들어 옵션을 적고, app.js에 연결해준다음

// ./swagger/swagger.js

const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

// Swagger 문서 정의
const swaggerOptions = {
    swaggerDefinition: {
        info: {
            title: 'Relay FairyTale',
            description:
                '릴레이 동화 서비스를 위한 Node.js환경 Swagger-jsdoc 방식 HTTP API 클라이언트 UI',
            version: '1.0.0',
        },
    },
    apis: ['./routes/*.js'], // API endpoint
};

const swaggerSpec = swaggerJsdoc(swaggerOptions);

module.exports = { swaggerUi, swaggerSpec };

// ./app.js

const express = require('express');
const cookieParser = require('cookie-parser');
const usersRouter = require('./routes/users.route');
const storiesRouter = require('./routes/stories.route');
const relaysRouter = require('./routes/relays.route');
const likesRouter = require('./routes/likes.route')
const { swaggerUi, swaggerSpec } = require('./swagger/swagger') // swagger

const app = express();
const PORT = 3018;

app.use(express.json());
app.use(cookieParser());

app.use('/', [usersRouter, storiesRouter]);
app.use('/stories/', [relaysRouter, likesRouter]);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec)) // swagger

app.listen(PORT, () => {
    console.log(PORT, '포트 번호로 서버가 실행되었습니다.');
});

이제 각 라우터 위에 아래와 같은 긴~~~~~ swagger 주석을 달면 된다.

/**
 * @swagger
 * /stories/{storyId}:
 *   get:
 *     summary: 동화 상세 조회 API
 *     description: 특정 동화의 상세 정보를 조회하는 API입니다.
 *     parameters:
 *       - in: path
 *         name: storyId
 *         description: 동화 ID
 *         required: true
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         description: 성공적으로 조회된 동화 데이터
 *         schema:
 *           type: object
 *           properties:
 *             story:
 *               type: object
 *               properties:
 *                 storyId:
 *                   type: integer
 *                 title:
 *                   type: string
 *                 content:
 *                   type: string
 *                 imageURL:
 *                   type: string
 *                 isFinished:
 *                   type: boolean
 *                 like:
 *                   type: integer
 *                 relays:
 *                   type: array
 *                   items:
 *                     type: object
 *                     properties:
 *                       relayId:
 *                         type: integer
 *                       content:
 *                         type: string
 *                       likeCount:
 *                         type: integer
 *                       user:
 *                         type: string
 *       404:
 *         description: 존재하지 않는 동화
 *         schema:
 *           type: object
 *           properties:
 *             errorMessage:
 *               type: string
 *       400:
 *         description: 동화 상세 조회 실패
 *         schema:
 *           type: object
 *           properties:
 *             errorMessage:
 *               type: string
 */

긴 주석을 모아서 swagger.json으로 작성해도 된다던데....... 일단 해보고 바꿔봐야겠다.