20. Spring_Swagger

🔥 Swagger(SpringDoc) 완전 정복 — 스프링부트 API 문서 자동 생성 원리 & URL 총표

Swagger(SpringDoc OpenAPI 3)는 Spring Boot에서 API 문서를 자동으로 생성해주는 대표적인 라이브러리입니다.
특히 어노테이션 없이도 자동으로 문서를 생성한다는 점이 SpringDoc의 가장 큰 장점입니다.
이 글에서는 Swagger의 전체 구조, 작동 방식, DTO 스캔 원리, 설정법, 접속 URL까지 모두 정리합니다.

---

0. pom.xml — Swagger(SpringDoc) 의존성

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>

• 이 한 줄로 Swagger UI, OpenAPI 문서, 자동 스캔 기능이 모두 활성화됩니다.
• Swagger 2.0이 아닌 OpenAPI 3.x 기반입니다.

---

1. application.yml 전체 설정 + Swagger 항목

spring:
  application:
    name: Ex01

  datasource:
    url: jdbc:mysql://localhost:3306/saveus?useSSL=false&characterEncoding=UTF-8
    username: root
    password: "3306"
    driver-class-name: com.mysql.cj.jdbc.Driver

  servlet:
    multipart:
      enabled: true
      max-file-size: 20MB
      max-request-size: 20MB

  jackson:
    time-zone: Asia/Seoul

server:
  port: 8080

mybatis:
  mapper-locations: classpath:mapper/*.xml
  configuration:
    map-underscore-to-camel-case: true

springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
    operationsSorter: method
    tagsSorter: alpha
  show-actuator: true

management:
  endpoints:
    web.exposure.include: "*"

📌 주요 Swagger 관련 항목 설명

• springdoc.api-docs.path → OpenAPI JSON 문서 URL
• /v3/api-docs가 스프링 전체 API 구조를 JSON으로 반환
• swagger-ui.path → Swagger UI 접속 URL
• operationsSorter → GET/POST 순서 정렬
• tagsSorter → 태그(컨트롤러) 사전순 정렬

이 설정만으로 Swagger UI가 자동 구성됩니다.

---

2. Swagger는 왜 어노테이션 없이도 작동하는가?

① Spring MVC 구조를 자동 분석 (핵심)

SpringDoc은 Spring 내부에서 등록된 아래 컴포넌트를 자동 스캔합니다.

• @RestController
• @Controller
• @RequestMapping
• @GetMapping / @PostMapping / @PutMapping / @DeleteMapping
• @RequestBody / @ResponseBody
• @PathVariable / @RequestParam

즉, 스프링 MVC가 어떤 URL을 매핑하는지 그대로 읽어 Swagger 문서로 변환합니다.

---

② DTO 구조를 Reflection으로 스캔

SpringDoc이 DTO를 분석하는 방식:

• 필드명
• 타입 정보(int, string, list 등)
• 중첩 클래스 여부
• 제네릭 타입
• 리스트 형태의 요소 타입
• Null 허용 여부

이 덕분에 Swagger 전용 어노테이션(@Schema 등)이 없어도 JSON Schema 문서를 자동 생성할 수 있습니다.

---

③ @JsonProperty 반영

DTO 필드에 @JsonProperty가 있을 경우 그대로 Swagger에 반영됩니다.

@JsonProperty("준비운동")
@JsonProperty("본운동")
@JsonProperty("정리운동")

Swagger UI에서도 다음처럼 표시됩니다.

• 준비운동
• 본운동
• 정리운동

---

3. Swagger에 표시되는 DTO 최종 예시

@Data
public class ExerciseRecommendResponseDto {

    @JsonProperty("user_id")
    private int userId;

    @JsonProperty("predicted_category")
    private String predictedCategory;

    @JsonProperty("routine")
    private Routine routine;

    @Data
    public static class Routine {

        @JsonProperty("준비운동")
        private String warmup;

        @JsonProperty("본운동")
        private List<String> main;

        @JsonProperty("정리운동")
        private String cool;
    }
}

→ Swagger UI에서는 JSON Schema 형태로 자동 변환되어 출력됩니다.

---

4. Swagger 접속 URL 정리 (Spring Boot 기준)

📌 Swagger UI 접속 URL

• http://localhost:8080/swagger-ui.html
• http://localhost:8080/swagger-ui/index.html

📌 OpenAPI JSON 문서(URL)

• http://localhost:8080/v3/api-docs
• http://localhost:8080/v3/api-docs/{컨트롤러명}   예) /v3/api-docs/user-controller

📌 YAML 문서(URL)

• http://localhost:8080/v3/api-docs.yaml

📌 Actuator + Swagger 통합 문서

• http://localhost:8080/actuator
• http://localhost:8080/actuator/openapi

---

5. Swagger(SpringDoc) 전체 동작 과정 요약

1. Spring Boot가 기동되면 → 모든 @RestController 스캔
2. 각 Controller의 핸들러(@GetMapping 등) 정보를 수집
3. 각 메서드의 Request/Response 타입 검사 (Reflection)
4. DTO 구조를 분석해 JSON Schema 생성
5. OpenAPI 문서 생성 → /v3/api-docs에 구성
6. Swagger UI가 /v3/api-docs를 읽어서 화면 렌더링

즉, Swagger 문서는 "Spring MVC + Jackson 기반 자동 스캔"으로 생성됩니다.

---

6. 최종 정리

• Swagger는 Spring MVC의 URL 구조를 자동 인식한다.
• DTO는 Reflection으로 스캔하여 JSON 스키마 생성.
• @JsonProperty는 문서에 그대로 반영된다.
• Swagger 전용 어노테이션(@Operation 등)은 선택이지 필수 아님.
• Swagger UI는 /swagger-ui.html 경로에서 접속.
• OpenAPI JSON 문서는 /v3/api-docs에서 확인.

Swagger(SpringDoc)의 핵심은 “어노테이션 없이도 완전 자동 문서화가 가능하다”는 점입니다.