Swagger UI란?

컨트롤러에 작성한 API를 자동으로 문서화해주는 것
/swagger-ui.html 또는 /swagger-ui/index.html로 접속할 수 있음
요청/응답 구조, 예제, 에러 코드까지 한 번에 정리됨
프론트/기획/QA랑 협업할 때 필수

Spring Boot에서 Swagger UI 만드는 방법

Spring Boot 3.x 기준
springdoc-openapi

의존성 추가(Gradle)

	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0'

Refresh gradle 한번 하고 프로젝트 가동한 다음
설정한 local port 로 접속
localhost:8080/swagger-ui/index.html
localhost:8080/swagger-ui.html

접속했는데 안 될 경우

Fetch error
response status is 500 /v3/api-docs

Swagger가 API 문서를 생성하다가 서버 내부 예외(500)가 터진 상태
대부분 Swagger 어노테이션 / DTO / Enum / 응답 타입 문제

@ExceptionHandler Swagger 충돌

Swagger가 예외 핸들러까지 문서화하다가 터짐

@ExceptionHandler(BusinessException.class)
public ResponseEntity<ErrorResponse> handle(BusinessException e) {
    return ...
}

수정

@Hidden
@RestControllerAdvice
public class GlobalExceptionHandler {
}

DTO 에 @Schema 어노테이션 달고 기본 생성자 안 적은 경우

@NoArgsConstructor

작성해줘야함
모든 필드 생성자
@AllArgsConstructor

Controller 메서드 파라미터 문제

Swagger가 이해 못함

@PostMapping("/login")
public ResponseEntity<?> login(HttpServletRequest request) {

수정

@PostMapping("/login")
public ResponseEntity<?> login(
    @RequestBody LoginRequest request
)

HttpServletRequest, Principal, Authentication
Swagger에 노출 안되게 해야 함

@Parameter(hidden = true) HttpServletRequest request

Enum 과 @Schema 필드 충돌

Enum에 @Schema 필드 있다면 제거

Swagger UI 설명 붙이는 방법

1. DTO에 설명 붙이기

@Schema(description = "")

2. Controller에 API 설명 추가

@Operation(
	summary = "",
    description = ""
)

3. 응답 코드 설명

@ApiResponses({
    @ApiResponse(responseCode = "200", description = "성공"),
    @ApiResponse(responseCode = "400", description = "필요 데이터 미비"),
    @ApiResponse(responseCode = "440", description = "각종 오류 - 상세 내용은 message 참조")
})

번외

@Data 어노테이션

@Getter
@Setter
@ToString
@EqualsAndHashCode
@RequiredArgsConstructor

전부 자동 생성

따로 쓰는 게 좋음