[SpringBoot Gradle] Swagger API 문서 적용하기

이 글은 Gradle, yml 기반 SpringBoot 프로젝트의 springdoc-openapi-ui 라이브러리를 적용하는 방법을 다룬다.

참고한 블로그 : [Spring Boot] Springdoc 라이브러리를 통한 Swagger 적용

1. 의존성 목록에 Springdoc 라이브러리 추가

build.gradle

dependencies {
	implementation 'org.springdoc:springdoc-openapi-ui:1.6.11' // Swagger
}

2. Swagger 사용을 위한 기본 설정

기본 세팅을 위해 SwaggerConfig.java, application.yml, ApiController.java 를 생성한다.

폴더 구조 참고하긔

📦 backend
└─ src
   ├─ java
   │  └─ com.capstone.backend
   │     └─ config
   │        └─ SwaggerConfig.java 
   │     └─ controller
   │        └─ ApiController.java
   └─ resources
      └─ application.yml

SwaggerConfig.java
Springdoc는 config 클래스에서 API 문서페이지의 기본 설명만 작성하고 나머지 설정은 모두 application.properties 혹은 👉applicatioin.yml에서 설정한다.

package com.capstone.backend.config;

import io.swagger.v3.oas.models.Components;
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()
                .components(new Components())
                .info(apiInfo());
    }

    private Info apiInfo() {
        return new Info()
                .title("Springdoc 테스트")
                .description("Springdoc을 사용한 Swagger UI 테스트")
                .version("1.0.0");
    }
}

application.yml

### Swagger ###
springdoc:
  packages-to-scan: com.capstone.backend.controller # 컨트롤러 가져오기
  default-consumes-media-type: application/json;charset=UTF-8
  default-produces-media-type: application/json;charset=UTF-8
  swagger-ui:
    path: /api-docs/
    disable-swagger-default-url: true
    display-request-duration: true
    operations-sorter: method

여기서 주의깊게 봐야할 부분은 문서의 접속 경로를 설정하는 path 항목이다. 나는 서버 실행 주소와 API 문서 주소를 분리해주기 위해서 path를 /가 아닌 /api-docs/로 매핑했다.

💡 결과
localhost:8080은 서버 주소를, localhost:8080/api-docs/는 Swagger API Docs를 가진다.

원격에 배포한 경우엔 localhost 자리에 고정아이피를 넣으면 된다.

3. Swagger 문서에 API 등록

ApiController.java

package com.capstone.backend.controller;

import io.swagger.v3.oas.annotations.Hidden;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@Tag(name = "예제 API", description = "Swagger 테스트용 API")
@RestController
@RequestMapping("/")
public class ApiController {
    @Operation(summary = "문자열 반복", description = "파라미터로 받은 문자열을 2번 반복합니다.")
    @Parameter(name = "str", description = "2번 반복할 문자열")
    @GetMapping("/returnStr")
    public String returnStr(@RequestParam String str) {
        return str + "\n" + str;
    }

    @GetMapping("/example")
    public String example() {
        return "예시 API";
    }

    @Hidden
    @GetMapping("/ignore")
    public String ignore() {
        return "무시되는 API";
    }
}

SpringBoot 프로젝트를 실행한 후 application.yml 속성에서 설정한 포트와 경로로 이동하면 API가 등록되어 있는 Swagger UI 문서를 확인할 수 있다.