Gradle 환경에서 Spring Boot 에 Swagger 2 적용하기

1. Dependency 적용

build.gradle에 swagger2 를 추가한다. (https://mvnrepository.com/artifact/io.springfox/springfox-swagger2/2.9.2)

Swagger 2 Dependency

dependencies {
...
	// Swagger 2
	compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
	compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
...
}

웹 UI 화면을 보려면, springfox-swagger-ui 를 추가해야 한다.

 

2. Swagger2 Enable

@EnableSwagger2 어노테이션을 추가하여 기능 활성화를 한다.

@EnableSwagger2 어노테이션은 main 쪽에 추가해도 되지만, 아래에서 생성할 Swagger2Config.java 에 추가해도 된다.

...
@EnableSwagger2
@SpringBootApplication
public class DemoApplication {

	public static void main(String[] args) {
		SpringApplication.run(DemoApplication.class, args);
	}

}
...

 

3. Swagger2 Config 설정

Config 설정을 위한 설정 클래스를 생성한다.

패키지 경로는 개인 취향에 따라 알아서 지정한다. 본 글에서는 com.example.demo.config.Swagger2Config.java 로 지정했다.

@Configuration
public class Swagger2Config {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();
    }
}

• .apis(): API 문서를 만들어줄 범위를 지정한다. 위 예제에서는 com.example.demo 하위 구조를 탐색하여 문서를 생성해준다.
• .paths(): API 의 URL 경로를 지정할 수 있다. .paths(PathSelectors.ant("api/v1/**")) 와 같이 하면 http://localhost/api/v1/ 하위 경로를 가지는 API에 대해 문서를 생성해준다.

옵션 설정

부가적으로 API 문서에 대한 내용을 수정하거나 추가하고 싶을때, 아래 코드와 같이 한다.

@EnableSwagger2
@Configuration
public class Swagger2Config {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ykgroup.dayco"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("제목 작성")
                .version("버전 작성")
                .description("설명 작성")
                .license("라이센스 작성")
                .licenseUrl("라이센스 URL 작성")
                .build();
    }
}

 

4. 결과 확인

실행하여 제대로 API 문서가 생성되었는지 확인한다.

• Swgger URL: http://<ip>:<port>/<base>/swagger-ui.html
• 예: http://localhost:8080/swagger-ui.html
  

웹 화면이 생성이 안된다면, dependency 에 swagger-ui를 추가했는지 확인한다. (높은 확률로 추가안한 경우가 많음)

 

Maven 환경에서 Swagger 적용하기

2020/02/18 - [Spring Boot] - Spring Boot 에 Swagger2 (스웨거) 적용하기