[Spring] API 문서 자동화: springdoc-openapi로 Swagger UI 만들기

 

 

📌 들어가며..

Spring Boot로 REST API를 개발하다 보면, API 명세를 프론트엔드 개발자나 같이 개발하는 팀원들과 공유하고 테스트할 수 있는 문서가 필요합니다. 

 

이럴 때 API 명세를 자동으로 문서화하기 위해 대표적으로 SpringFox나 SpringDoc을 사용합니다. 

하지만 Spring Boot 3부터는 SpringFox를 더 이상 지원하지 않기 때문에, SpringDoc을 사용하는 것이 훨씬 안정적입니다. 

 

SpringFox에서 SpringDoc으로 마이그레이션하는 방법도 공식 문서에 잘 정리되어 있습니다. 

 

 

적용 환경

• Spring Boot 3.5.0
• Java 21 
• Gradle
• springdoc-openapi 2.8.8

 

 

📌 springdoc-openapi 라이브러리란?

Spring Boot REST API를 자동으로 문서화해주는 Java 기반의 라이브러리입니다. 

springdoc-openapi 라이브러리를 적용하면 런타임에 애플리케이션 구조와 애노테이션을 분석해 OpenAPI 3 형식의 명세를 자동 생성하고, Swagger UI로 브라우저에서 API 명세를 쉽게 확인할 수 있습니다. 

 

✅ 핵심 기능

1. @RestController, @RequestMapping, @Operation, @Schema 등 애노테이션을 분석해 OpenAPI 명세 자동 생성
2. OpenAPI 명세를 JSON 형식으로 제공
3. API 문서를 시각적으로 볼 수 있고, 테스트도 할 수 있도록 Swagger UI 제공 
4. Spring Boot 3.x, Java 17 ~ 21 지원
5. Validation(@NotNull, @Size 등) 정보를 문서화에 자동 반영
6. OAuth 2 인증, Spring Security 연동 가능

 

 

 

📌 도입 방법

1️⃣ 의존성 추가 (build.gradle)

dependencies {
    // Spring Web (Spring-boot-starter-web을 사용하지 않으면 Swagger UI가 동작하지 않을 수 있음)
    implementation 'org.springframework.boot:spring-boot-starter-web'

	// Springdoc OpenAPI
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.8'
}

spring-boot-starter-web을 사용하지 않으면 Swagger UI가 동작하지 않을 수 있습니다. 

 

 

2️⃣ OpenAPI 기본 정보 설정 (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 OpenApiConfig {

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

}

이 Config 파일은 springdoc-openapi에서 제공하는 OpenApi 객체를 빈으로 등록해서, API 문서의 메타 정보를 설정하기 위한 Spring 설정 클래스입니다. 

Config 클래스가 없어도 Swagger UI는 실행되지만, Swagger UI에 표시되는 API 제목, 설명, 버전 등 메타 데이터를 정해주거나 보안 설정을 하고 싶을 때 사용하면 됩니다. 

 

 

3️⃣ Controller에서 Swagger 애노테이션 적용해보기 

@Tag(name = "User", description = "User API")
@RestController
@RequestMapping("/users")
public class UserController {

    @Operation(summary = "회원가입", description = "이메일, 비밀번호, 닉네임으로 회원가입을 합니다.")
    @PostMapping("/signup")
    public CommonApiResponse<String> signup(@RequestBody SignUpRequest signUpRequest) {
        return CommonApiResponse.success("회원가입이 완료되었습니다.");
    }

    @Operation(summary = "이메일 중복 확인", description = "이메일 중복 확인을 합니다.")
    @PostMapping("/email")
    public CommonApiResponse<String> checkEmail(@RequestBody EmailCheckRequest emailCheckRequest) {
        return CommonApiResponse.success("사용 가능한 이메일입니다.");
    }
}

@Tag로 API 컨트롤러의 기능을 구분하기도 하고, @Operation로 하나의 API 엔드포인트에 대한 요약, 설명, 응답 등 상세 정보를 설정하기도 합니다. 

 

 

4️⃣ Swagger UI 설정 커스터마이징 (application.yml) -> 필수 X

springdoc:
  api-docs:
    enabled: true # OpenAPI 명세(JSON) 노출 여부 설정
  swagger-ui:
    enabled: true # Swagger UI 사용 여부 설정
    path: /swagger-ui.html # Swagger UI 접근 경로 (기본값: /swagger-ui/index.html)
    tags-sorter: alpha # 태그를 알파벳순으로 정렬
    operations-sorter: alpha # API 엔드포인트를 알파벳순으로 정렬
    display-request-duration: true # 요청 처리 시간 표시

API 문서 노출 여부, UI 경로, 정렬 방식, 요청 시간 표시 여부 등을 설정하고, 필수는 아닙니다. 

 

 

 

 

 

📌 도입 결과 

✅ 결과 확인 방법 (로컬)

• OpenApI JSON
  • http://localhost:8080/v3/api-docs
• Swagger UI
  • http://localhost:8080/swagger-ui/index.html
  • 또는 http://localhost:8080/swagger-ui.html (application.yml 설정 필요)

 

배포 환경에서는 <배포 주소>/swagger-ui/index.html 또는 <배포 주소>/swagger-ui.html에서 확인할 수 있습니다. 

 

 

 

 

 

 

 

 

 

📌 자주 사용하는 Swagger(OpenAPI) 애노테이션 정리 

springdoc-openapi는 Swagger(OpenAPI) 애노테이션을 기반으로 문서를 자동 생성합니다. 

 

@Operatioin

• 각 API 엔드포인트의 설명을 정의합니다. 
• 속성
  • summary : 각 API 항목의 한줄 제목
  • description : API에 대한 상세 설명
  • tags : API 그룹 구분용 태그
  • responses : API 응답 코드별 설명 
• @Operation JavaDoc

@Tag

• 컨트롤러 단위로 API를 그룹화할 수 있는 태그를 정의합니다.
• @Tag JavaDoc

@Parameter

• 개별 파라미터에 대한 설명을 추가할 수 있습니다. 
• @Paramter JavaDoc

@Schema

• DTO 필드에 대한 설명이나 예시를 정의합니다. 
• 속성
  • description : 필드의 설명
  • example : 예시 값
  • required : 필수 입력값인지 여부 
  • minLength, maxLength : 문자열 길이에 대한 최소/최대 제한
• @Schema JavaDoc

@ApiResponse, @ApiResponses

• 특정 API의 응답 코드를 문서화합니다.
• @ApiResponse JavaDoc

@SecurityRequirement

• JWT나 OAuth 같은 API 보안 요구사항을 정의합니다. 
• @SecurityRequirement JavaDoc

 

 

 

---

참고 

• SpringDoc 공식 문서
• Swagger 공식 문서
• JavaDoc