java gradel 프로젝트에 swagger 설정 및 사용방법을 정리

Java Gradle 프로젝트에서 Swagger를 설정하고 사용하는 대표적인 방법은 springdoc-openapi를 적용하는 것입니다. 아래에 단계별로 정리합니다.

1. Gradle 의존성 추가

build.gradle에 아래 의존성을 추가합니다.

groovy

dependencies {

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

}

버전에 따라 최신 버전(예: 2.0.2/2.3.0 등)을 선택할 수 있습니다.

2. Swagger 설정 클래스 생성

Swagger의 기본 정보, 보안 설정 등이 필요하다면 아래처럼 설정 클래스를 추가합니다.

java

package com.example.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 { @Bean public OpenAPI openAPI() { return new OpenAPI() .info(new Info() .title("프로젝트 API 문서") .description("API에 대한 설명 작성") .version("1.0.0")); } }

JWT 인증 등 추가 설정이 필요할 경우 SecurityScheme 등도 등록할 수 있습니다.

3. application.yml 설정(옵션)

추가적으로 API 문서의 경로나 세부 옵션을 설정할 수 있습니다.

text

springdoc:

  packages-to-scan: com.example.controller

  swagger-ui:

    path: /api-docs/

    display-request-duration: true

접속 경로(/api-docs/) 등은 프로젝트 요구에 맞게 설정합니다.

4. Controller에 Swagger annotation 사용

java gradel 프로젝트에 swagger 설정 및 사용방법을 정리

Swagger 문서에 추가적인 정보와 예시를 제공하려면 Controller에 annotation을 추가합니다.

java

import io.swagger.v3.oas.annotations.tags.Tag;

import io.swagger.v3.oas.annotations.Operation;

import org.springframework.web.bind.annotation.*;
@Tag(name = "User", description = "사용자 관련 API")

@RestController

@RequestMapping("/user")

public class UserController {

@Operation(summary = "이름 목록 반환", description = "전체 이름 리스트를 반환합니다.") @GetMapping("/names") public List<String> getNames() { return List.of("홍길동", "이몽룡", "성춘향"); } }

@Tag, @Operation, @Parameter 등을 활용해 문서를 더욱 정교하게 작성할 수 있습니다.

5. Swagger UI 실행 및 확인

서버를 실행하고 Swagger UI에 접속(MVC의 경우 기본적으로 /swagger-ui.html 또는 /api-docs/와 같이 설정한 경로로 접근).
자동으로 API 문서가 생성되며, 해당 UI에서 요청 테스트도 가능합니다.

추가 참고사항

springdoc-openapi는 Spring Boot 3.x 버전 이상에서 공식적으로 권장되는 라이브러리입니다.
SpringFox는 2.x 버전에서 많이 사용되었으나, 최근에는 springdoc-openapi를 많이 사용합니다.

위 단계대로 설정하면 Java Gradle 프로젝트 내에서 Swagger를 통한 API 문서화와 테스트가 가능합니다.