[SpringBoot] Gradle 빌드툴에서 Swagger 적용 방법과 기본적인 문서 적용 방법

Swagger는 API 문서를 생성하고 관리하는 도구인 API Docs 이다. Swagger가 springfox, springdocs 2종류가 있는데 springfox는 업데이트가 중단돼서 현재는 springdocs만 사용되고 있는 중이다. springfox를 사용해도 되긴 한데 springboot 버전 2점대에서만 사용 할 수 있다.

 

springdocs는 그게 2버전으로 나뉘는데 1.x, 2.x 버전으로 나뉘는데, 1.x 버전은 springboot 버전 2.x 버전에서 사용되고 2.x 버전은 springboot 버전 3.x 버전에서 사용된다. 각 최신 버전은 아래 URL에서 확인할 수 있다.

1.x 버전 공식 문서는 URL : https://springdoc.org/v1/ 
2.x 버전 공식 문서 URL : https://springdoc.org/

 

 

swagger springdoc적용 방법

swagger를 추가하는 방법은 간단하다. 

 

build.gradle 파일에서 아래 의존성을 추가해주면 된다. 아래는 springdoc 1.8버전 의존성을 추가한것이다. 만약에 2.4버전을 추가하고 싶으면 아래 1.8.0을 지우고 2.4.0으로 수정해주면 된다.

implementation 'org.springdoc:springdoc-openapi-ui:1.8.0'

 

그리고 아래 URL 접속 하면 아무것도 설정 되지 않은 swagger 화면이 나올것이다.

localhost:8080/swagger-ui/index.html

 

 

swagger 타이틀 메뉴 설정 방법

SwaggerConfig 클래스를 만들고 GroupedOpenApi 빈을 생성해서 메뉴를 설정할수 있고

OpenAPI 빈을 만들어서 Title을 설정할 수 있다.

@Configuration
public class SwaggerConfig {
    @Bean
    public GroupedOpenApi publicApi() {
       return GroupedOpenApi.builder()
          .group("v1-clothstar")
          .pathsToMatch("/**")
          .build();
    }

    @Bean
    public OpenAPI springShopOpenAPI() {
       return new OpenAPI().info(new Info().title("API").description(" API 명세").version("v0.1"));
    }
}

 

 

Controller와 api 문서 적용 방법

Controller 클래스에서 @Tag로 Controller에 대한 설명과 @Operation 으로 api에 대한 설명을 추가할 수 있다.