Spring에서 Swagger 사용 방법

Spring에서 Swagger(현재는 OpenAPI 명칭 사용)는 REST API를 자동으로 문서화해주는 도구.
백엔드 개발할 때 API 명세를 따로 작성할 필요 없이, 소스 코드의 어노테이션 정보로 API 문서를 자동 생성해줌.

---

Swagger(OpenAPI)란?

Spring 프로젝트에서 API 문서화, 테스트, 공유를 쉽게 할 수 있도록 도와주는 라이브러리입니다.
특히 Swagger UI는 API를 웹 브라우저에서 바로 테스트할 수 있도록 예쁜 화면을 제공합니다.

---

Swagger(OpenAPI)를 쓰면 좋은 점

기능	설명
API 문서 자동 생성	@RestController, @GetMapping 등 어노테이션 기반으로 자동 문서화
Swagger UI 제공	브라우저에서 API 테스트 가능
Client 코드 자동 생성	Java, JS, Python API 클라이언트 코드 자동 생성
팀 커뮤니케이션 개선	프론트/백 간 API 협업 쉬워짐
버전 관리 용이	변경된 API 자동 업데이트

---

Spring에서 Swagger 사용 방법

Spring Boot 기준 가장 많이 사용하는 라이브러리:

✔ springdoc-openapi (권장)

과거 swagger2(springfox)는 유지보수 끊겨서 요즘은 springdoc-openapi를 많이 씀.

1) Gradle/Maven 의존성 추가

Maven

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

2) Swagger UI 접속 경로

부트 실행 후:

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

또는

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

---

기본 사용 예제

✔ Controller에 적용되는 어노테이션 예시

@RestController
@RequestMapping("/api/users")
public class UserController {

    @Operation(summary = "유저 조회", description = "ID로 유저 정보를 조회한다.")
    @GetMapping("/{id}")
    public UserResponse getUser(
            @Parameter(description = "유저 ID") @PathVariable Long id) {

        return new UserResponse(id, "Peter");
    }
}

---

Swagger 설정(옵션)

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI apiInfo() {
        return new OpenAPI()
                .info(new Info()
                        .title("My API")
                        .description("API Documentation")
                        .version("1.0.0"));
    }
}

---

Swagger UI 화면 예시 기능

• API 목록 자동 생성
• 각 API 클릭 시 요청/응답 스펙 표시
• JSON Body 자동 예시 출력
• Try it out → API 호출 테스트 가능
• Authentication(JWT) 적용 가능

---

JWT 인증 적용(옵션)

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .components(new Components()
                .addSecuritySchemes("BearerAuth",
                    new SecurityScheme()
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("bearer")
                        .bearerFormat("JWT")
                ))
            .addSecurityItem(new SecurityRequirement().addList("BearerAuth"));
}

Swagger UI의 상단에서 Authorization → JWT 입력하면 API 테스트 가능해짐.

---

Swagger 사용 시 주의사항

• Springfox(swagger2)는 Spring Boot 3에서 동작 안 함 → springdoc-openapi 추천
• 보안 이슈 때문에 운영 서버에서는 swagger-ui 비활성화 권장
• DTO 설명을 잘 작성하면 API 문서 품질이 높아짐