Swagger / OpenAPI 실무 심화

openapi: 3.0.0
info:
  title: PMS API
  version: 1.0.0
paths:
  /products:
    get:
      summary: 상품 목록 조회
      responses:
        '200':
          description: 성공
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
components:
  schemas:
    Product:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }

paths는 엔드포인트, components는 재사용 가능한 계약입니다.

npm install swagger-jsdoc swagger-ui-express

const swaggerJsdoc = require("swagger-jsdoc");

const options = {
  definition: {
    openapi: "3.0.0",
    info: { title: "PMS API", version: "1.0.0" },
    servers: [{ url: "http://localhost:3000" }],
  },
  apis: ["./routes/*.js"],
};

module.exports = swaggerJsdoc(options);

const swaggerUi = require("swagger-ui-express");
const swaggerSpec = require("./swagger");

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

/api-docs에서 Swagger UI를 확인합니다.

/**
 * @swagger
 * /products/{id}:
 *   get:
 *     summary: 상품 단건 조회
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema: { type: integer }
 *     responses:
 *       200:
 *         description: 조회 성공
 *       404:
 *         description: 상품 없음
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 error: { type: string, example: "Product not found" }
 */

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

paths:
  /products:
    post:
      security:
        - bearerAuth: []
      summary: 상품 등록 (인증 필요)