[Sping Boot] API 자동 문서화를 위한 Swagger 사용법

Swagger를 사용하는 이유

API 문서는 백엔드-프론트엔드 협업에서 필수 요소입니다.
그동안 프로젝트를 진행하면서 항상 API 명세서를 직접 작성했는데, API 변경이 잦을 때마다 문서를 일일이 수정하는 것이 꽤 번거로웠습니다.

이 문제를 해결해주는 도구가 바로 Swagger입니다.
Swagger를 사용하면:

• API 문서를 자동으로 생성할 수 있고
• UI 환경에서 API를 직접 테스트할 수 있으며
• 문서의 일관성 유지가 가능해집니다.

결과적으로 개발 효율성과 협업 생산성을 크게 높여줍니다.

---

Swagger 설정 방법

1. 의존성 추가

Spring Boot 3.x 버전부터는 아래 한 줄만 추가하면 됩니다.

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

 

---

2. Swagger 기본 설정

Swagger.java 파일을 생성하고 아래 코드를 작성해줍니다.

package org.mySite.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    private Info info = new Info()
            .title("Swagger Test")
            .version("0.0.1")
            .description("<h3>Swagger test</h3>");

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI().info(info);
    }
}

 

서버를 실행하고 다음 주소로 접속하면 Swagger UI를 확인할 수 있습니다.

• http://localhost:8080/swagger-ui/index.html (Spring Boot 3.x)
• http://localhost:8080/swagger-ui.html (Spring Boot 2.x)

 

 

---

더 상세한 API 문서 만들기

Annotation을 활용하면 API 설명, 요청/응답 예시, DTO 설명까지 추가할 수 있습니다.

---

1. Controller에서 문서화

• @Tag → 컨트롤러 그룹화
• @Operation → API 요약 + 설명
• @ApiResponses → HTTP 응답 코드 + 설명

@Controller
@Tag(name = "cookie로그인", description = "쿠키 로그인 컨트롤러")
@RequiredArgsConstructor
@RequestMapping("/cookie-login")
public class CookieLoginController {

    @GetMapping("/")
    @Operation(summary = "쿠키 로그인 메인 페이지", description = "쿠키 로그인 동작을 위한 메인 페이지입니다.")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "쿠키 로그인 페이지 로드 성공", content = @Content),
            @ApiResponse(responseCode = "400", description = "잘못된 요청", content = @Content),
            @ApiResponse(responseCode = "500", description = "서버 에러", content = @Content)
    })
    public String home(@CookieValue(name = "userId", required = false) Long userId, Model model){
        ...
    }
}

 

---

2. DTO에서 문서화

• @Schema → DTO 필드 설명 + 예시 값

public class LoginRequest {

    @NotBlank(message = "로그인 아이디를 입력하세요")
    @Schema(description = "로그인 시도한 아이디", example = "soojin")
    private String loginId;

    @NotBlank(message = "비밀번호를 입력하세요")
    @Schema(description = "입력된 비밀번호", example = "1234")
    private String password;
}

Swagger UI에서 DTO 구조를 직관적으로 확인할 수 있어, 프론트엔드 개발자와 협업이 훨씬 수월해집니다.

---

Swagger 도입 효과

Swagger를 도입하면 다음과 같은 장점이 있습니다:

• API 문서를 자동 생성하여 관리 부담 감소
• UI 환경에서 실시간 테스트 가능
• 프론트엔드-백엔드 협업 효율성 향상
• API 변경 시 자동 반영 → 일관성 유지
• 코드와 문서를 따로 관리하지 않아도 됨