[ TIL ] Day 34 - Swagger 전격 분석하기! 📋🖊️

🗓️ 수업 일자 : 2025.11.12

✨ 오늘의 수업 평가 :  [ HARD ]  오늘은 좌절 연속… 그래도 기록은 남긴다 🥲✍️

 

... 머리가 너무 아파서 오늘 개인 평가는 쉽니다..

 

👩‍💻 [개인 / 팀 프로젝트] 오늘 작업 내용 💻
- 팀 프로젝트 작업 : 그룹 생성 API 에 이미지 업로드 기능 추가

 

📝  오늘 배운 내용  

- Swagger 기본 내용 정리

---

Swagger 기본 내용 정리 

1. Swagger란? 

Swagger는 OpenAPI Specification (OAS) 기반으로 동작하는 문서화 도구로,

Express 서버 기준으로는 대부분 Swagger UI + Swagger-jsdoc 조합을 사용함.

 

- swagger-jsdoc : JSON 스펙 자동 생성
- swagger-ui-express : 그 JSON을 UI로 보여줌

 

Swagger test 진행하여 URL로 API 문서 출력한 예시

 

 

2. 설치 및 사용 방법

1) 설치 방법 

   -  터미널에서 명령어를 사용하여 설치 : npm install swagger-ui-express swagger-jsdoc

   

2) 사용 방법 

   - app.js 파일과 각 route.js 파일에 Swaggar 구문 입력

[ app.js ]
import swaggerUi from "swagger-ui-express";
import swaggerJSDoc from "swagger-jsdoc";

// Swagger 설정
const options = {
  definition: {
    openapi: "3.0.0", // 표준 문법 사용 선언
    info: { // custom 가능 영역, 프로젝트의 정보를 작성
      title: "Team Project API Docs",
      version: "1.0.0",
      description: "Swagger 문서 테스트",
    },
    servers: [{ url: "http://localhost:3000" }], // baseURL 설정
  },
  apis: ["./routes/*.js"], // Swagger 주석 읽을 위치
};

 

[ product-route.js ]

// [최상단] Product 전체 분류 - 전역 선언 영역
/**
 * @swagger
 * tags:
 *   name: Product
 *   description: 상품 관리 API 설정
 */
 
 // ======================================================
 // [라우트 선언 전] Product 요청 API 별 셋팅
 // product get 셋팅 예시
 /**
 * @swagger
 * /products:
 *   get:
 *     summary: 모든 상품 조회 가능
 *     tags: [Product]
 *     description: 등록된 모든 상품을 조회합니다.
 *     responses:
 *       200:
 *         description: 성공적으로 상품 목록을 반환
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/components/schemas/Product'
 */
 
 router.get("/", productGet);
 
  // product post 셋팅 예시
 /**
 * @swagger
 * /products:
 *   post:
 *     summary: 새로운 상품 등록
 *     tags: [Product]
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/ProductInput'
 *     responses:
 *       201:
 *         description: 상품 등록 성공
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/Product'
 */
 
 router.post("/", productPost);
 
 ...
 // ======================================================
 // [최하단] Product 스키마 설정
 /**
 * @swagger
 * components:
 *   schemas:
 *     Product:
 *       type: object
 *       properties:
 *         id:
 *           type: number
 *           example: "123"
 *         name:
 *           type: string
 *           example: "양말"
 *         price:
 *           type: number
 *           example: 3500
 *         stock:
 *           type: integer
 *           example: 100
 *     ProductInput:
 *       type: object
 *       required: [name, price, stock]
 *       properties:
 *         name:
 *           type: string
 *           example: "솜이불"
 *         price:
 *           type: number
 *           example: 4900
 *         stock:
 *           type: integer
 *           example: 50
 */

 

test 파일 정보 : https://github.com/KimDay366/dev_self-study/tree/main/swaggerTest

dev_self-study/swaggerTest at main · KimDay366/dev_self-study

 

3) route 파일 설정 세부 정보 

 

1. [최상단] Product 전체 분류 설명

• name : 요청 API 정보의 tags 값으로 사용
• description : 분류 명칭 옆으로 태그 이름 나옴

[최상단] Product 전체 분류 영역 구조 확인

 

 

2. [중간] Product 요청 API 별 셋팅 

    - 요청 API에 따라 사용하는 값이 다르므로 위에 있는 GIT 링크 확인!! 

• /products : 실제 요청 api에서 사용 할 경로 명
• get : 요청 API 메서드명
• summary : 해당 요청에 대한 제목
• tags: [상단에 작성한 tags - name] 작성, 다른 태그일 경우 해당 태그 작성 가능
• description: 해당 API를 눌렀을 때 나오는 간략 설명
• responses : (응답에 대한 정보를 하단에 기재)
  • 200: (요청 API에 따라 여러 응답 코드 작성 가능)
    • description: 작업 성공시 나올 메세지 작성
    • content: (response의 body를 받아오는 셋팅)
      • application/json: (요청에서 사용 할 언어 셋팅)
      • schema: (별도의 내용을 작성하지 않음, 최 하단에 스키마를 사용하게 됨)
      • type: array (여러 데이터를 보는 GET에서만 주로 사용, 다른 요청에서는 다른 타입을 사용)
      • $ref: '#/components/schemas/설정한 스키마 모델명'

[중간] Product 요청 API 별 셋팅 구조 확인

 

 

3. [최하단]  Product 스키마 설정

• 'schemas: ' 라인 아래로 사용할 스키마 모델을 설정
• 라우터 Swagger 설정 시 [ $ref: '#/components/schemas/___ ] 에 사용할 스키마를 설정한다 생각하면 됨.
• 모델 필드 명을 작성 해 주고, 해당 타입 + 샘플을 같이 작성 해 줌

[최하단] Product 스키마 설정 자세히 보기

---

 

📃 내일은 뭘 배울까 🤔

- git & github 다시 정리