[Spring] Swagger 3.0.0 적용

1. Swagger 란?

Swagger 는 간편하게 API Spec 문서를 자동으로 작성하고 이를 편집하여, 화면에 출력할 수 있게 해주는 기능 들을 제공하는 오픈 소스 툴이다. 서버의 API 리스트를 문서화하여 화면에 출력하여 보여주고, 파라미터를 직접 입력하여 API 테스트도 수행할 수 있다.

 

RESTful 하게 구현한 SpringBoot 에도 Swagger 를 적용하여 REST api 들의 문서화와 테스트를 수행할 수 있다.

아래의 예제에서는 Swagger 3.0.0 을 사용하여 Swagger 를 적용하였다.

2. Swagger 설정

Swagger 를 SprintBoot 에 적용하기 위해서는 우선 build.gradle 에 의존성을 추가해주어야 한다.

 

implementation 'io.springfox:springfox-boot-starter:3.0.0'
implementation 'io.springfox:springfox-swagger-ui:3.0.0'

 

Swagger 사용을 위한 의존성을 추가해준 후에는 Swagger 설정을 해주어야 한다. 이때 Swagger Configuration 을 설정한 클래스를 작성하고 해당 클래스에 Configuration 어노테이션을 추가해주어 웹 서비스에 Configuration 을 추가해준다.

 

@Configuration
public class SwaggerConfig {
   
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .useDefaultResponseMessages(true) // Swagger 에서 제공해주는 기본 응답 코드 (200, 401, 403, 404) 등의 노출 여부
                .apiInfo(apiInfo()) // Swagger UI 로 노출할 정보
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.spring.practice.rest")) // api 스펙이 작성되어 있는 패키지 (controller)
                .paths(PathSelectors.any()) // apis 에 위치하는 API 중 특정 path 를 선택
                .build();
    }

    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot Practice Rest API Documentation")
                .description("springboot rest api practice.")
                .version("0.1")
                .build();
    }   
}

 

위의 설정 예제에서 api() 메서드는 사용할 api, 여기에서는 Swagger 의 기본 설정을 위한 Bean 을 정의하는 메서드이다. apiInfo() 메서드는 Swagger UI 에 출력될 API 내용을 정의하는 메서드로 api() 메서드에서 설정할 때 사용된다.

 

- Docket: Springfox 프레임워크의 api 들에 대한 기본 인터페이스 설정을 위한 빌더이다. 이 예제에서는 Swagger 의 기본 설정을 위한 Bean 으로 사용된다.

- userDefaultResponseMessages(): Swagger 에 미리 정의되어 있는 기본 응답 메시지를 사용할 지에 대한 여부를 설정하는 메서드.

- apiInfo(): Swagger API 문서에 대한 설명을 표기하는 메서드.

- select(): 선택된 api 에 대한 빌더를 초기화한다.

- apis(): Swagger API 문서로 만들기 API 메서드들이 작성되어 있는 패키지 (Controller 를 포함하고 있는 패키지) 의 경로를 지정해준다.

- paths(): 특정 Path 를 지정하여 apis() 에 지정된 경로 중에서 원하는 경로의 api 만 문서화한다.

- build(): ApiSelectorBuilder 를 빌드한다. Docket 타입을 반환한다.

 

자세한 내용은 springfox 의 자바 문서에서 확인할 수 있다.

 

- https://springfox.github.io/springfox/javadoc/current/springfox/documentation/spring/web/plugins/Docket.html

Docket

3. Swagger 실행

위의 설정을 하고 서버를 실행하면 Swagger 는 자동으로 실행된다.

로컬에서 서버를 실행하고 http://localhost:8080/swagger-ui/index.html 로 접속하면 Swagger UI 로 생성된 문서화 된 API 목록을 웹페이지로 확인할 수 있다.

[reference]

- https://velog.io/@wotj7687/Spring-Boot-Swagger-3.0.0-%EC%A0%81%EC%9A%A9

Spring Boot + Swagger 3.0.0 적용

- https://velog.io/@gillog/SpringBoot-Swagger-%EC%84%A4%EC%A0%95%ED%95%98%EA%B8%B0

[SpringBoot] Swagger 설정하기