[spring - swagger] springdoc-openapi를 이용한 스프링 부트 3 스웨거 간단 적용

springdoc-openapi로 스프링 부트 3에 스웨거 적용하기

이 문서는 springdoc-openapi를 사용하여 스프링 부트 3에 스웨거를 적용하는 방법에 대해 설명합니다.

목표

• 스프링 부트 3에서 스웨거를 어떻게 적용하는지 이해하고 실제로 적용해 보기
• API 문서화 작업의 효율성 향상

적용 순서

1. 스웨거 의존성 추가: Spring Boot 프로젝트의 pom.xml 또는 build.gradle 파일에 Swagger 의존성을 추가합니다.
2. 스웨거 UI 확인: 웹 브라우저에서 Swagger UI를 열어, 정의한 API 문서가 잘 생성되었는지 확인합니다.

버전 정보

• 적용일: 2024년 4월 18일
• 사용 언어: Java 17
• 사용 프레임워크: Spring Boot 3.2.4
• 빌드 도구: gradle

참고 사이트

• springdoc-openapi 공식 문서

OpenAPI 3 Library for spring-boot

적용 방법

1. build.gradle 파일에 springdoc-openapi 라이브러리를 추가합니다.

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

 

이외 전체 build.gradle 정보

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.4'
    id 'io.spring.dependency-management' version '1.1.4'
}

group = 'org'
version = '0.0.1-SNAPSHOT'

java {
    sourceCompatibility = '17'
}

configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    compileOnly 'org.projectlombok:lombok'
    developmentOnly 'org.springframework.boot:spring-boot-devtools'
    annotationProcessor 'org.projectlombok:lombok'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'

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

tasks.named('test') {
    useJUnitPlatform()
}

2. 테스트를 위한 Controller를 추가합니다.

- org.springwebswaggertest.controller.HelloController.java

package org.springwebswaggertest.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping("/api/hello1")
    public String hello1() {
        return "hello";
    }

    @GetMapping("/api/hello2")
    public String hello2(@RequestParam String param) {
        return param;
    }
}

3. Spring boot를 실행합니다.

4. http://localhost:8080/swagger-ui/index.html 에 접속하여 Swagger UI를 확인합니다.

5. 프로젝트 폴더 및 파일에 대한 정보입니다.

결론

라이브러리를 추가하는 것만으로 아무런 추가 설정 없이 쉽게 스웨거를 적용할 수 있었습니다.