API 명세서 자동화 - swagger (feat. express.js)

Swagger의 주요 특징

자동화된 API 명세서 생성

코드 주석을 통해 API 명세서를

자동으로 생성할 수 있다

사용자 친화적인 UI

누구나 API 명세서를

시각적으로 이해할 수 있다

API 테스트 기능

직접 API를 호출하고

테스트할 수 있는 기능을 제공

 

swagger 관련 패키지 설치

npm install swagger-jsdoc swagger-ui-express

 

 

swagger 설정 파일 생성

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

const swaggerOptions = {
  swaggerDefinition: {
    openapi: '3.0.0',
    info: {
      title: 'My API',
      version: '1.0.0',
      description: 'API documentation with Swagger'
    },
    servers: [
      {
        url: 'http://localhost:3000', // IP와 포트번호 설정
      },
    ],
  },
  apis: ['./routes/*.js'], // 실제 API 경로 넣기
};

const swaggerDocs = swaggerJsDoc(swaggerOptions);

module.exports = { swaggerUi, swaggerDocs };

 

swagger 미들웨어 추가

const express = require('express');
const { swaggerUi, swaggerDocs } = require('./swagger');

const app = express();

// swagger UI 설정
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
  // 서버 실행 후 명세서를 확인할 수 있는 URL
  console.log('Swagger docs available at http://localhost:3000/api-docs'); 
});

 

swagger 주석 추가

/**
 * @swagger
 * /api/feed:
 *   post:
 *     summary: Create a new feed
 *     description: Create a new feed for the user
 *     tags:
 *       - Feed
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               description:
 *                 type: string
 *                 description: The description of the feed
 *                 example: "A beautiful sunset!"
 *               imageUrls:
 *                 type: array
 *                 items:
 *                   type: string
 *                 description: Array of image URLs
 *                 example: ["https://example.com/image1.jpg", "https://example.com/image2.jpg"]
 *     responses:
 *       201:
 *         description: Feed created successfully
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 message:
 *                   type: string
 *                   example: "Feed created"
 *                 result:
 *                   type: object
 *                   description: Details of the created feed
 *       400:
 *         description: Invalid input data
 *       500:
 *         description: Server error
 */
router.post('/', feedController.createFeed);

 

서버 실행 후 url 접속