Swagger 설정하기

• swagger io: https://swagger.io/specification/

OpenAPI Specification - Version 3.0.3 | Swagger

• https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api 

Setting Up Swagger 2 with a Spring REST API | Baeldung

 

we'll look at Swagger 2 for a Spring REST web service, using the Springfox implementation of the Swagger 2 specification.

Swagger 2 명세를 구현한 Springfox 를 이용해서 spring rest 웹서비스를 위한 swagger 를 사용할 수 있다.

 

1. Swagger 관련 의존성을 추가한다. 

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>

<!-- 주로 아래의 의존성과 세트로 사용하는듯 -->
<dependency>
 	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
  	<version>3.0.0</version>
</dependency>

Spring Boot 가 기반이 되는 프로젝트에는 아래와 같이 스타터를 추가해도된다. 

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

 

2. Swagger 를 통해 API 노출하기 위해 관련 설정을 해준다.

@Configuration
@EnableSwagger2
public class SpringFoxConfig {
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build().apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        String description = "Welcome My Moment";
        return new ApiInfoBuilder()
                .title("SWAGGER TEST")
                .description(description)
                .version("1.0")
                .build();
    }
}

• Docket bean을 통해서 설정한다.
• select() 메소드를 선택하게되면 ApiSelectorBuilder 에 의해 특정 API만 노출될 수 있도록 설정이 가능하다.
• ApiSelectorBuilder 는 Swagger에 의해 노출할 endpoints 를 제어할 방법을 제공한다.
  • any() 는 가능한 모든 API의 documentation을 만든다.
  • RequestHandlerSelectors.basePackage("com.test.main.v1") => 해당 패키지 아래의 API 노출
  • RequestHandlerSelectors.withClassAnnotation(RestController.class) => RestController 어노테이션 클래스의 API 만 노출
  • RequestHandlerSelectors.withMethosAnnotation(ApiOperation.class) => @ApiOperation 어노테이션을 사용한 API 만 노출

(any()를 사용했더니 basic-error-controller 가 디폴트로 나오길래 안나오게 하고 싶어서 basePackage() 으로 바꿨당)

 

 

3. http://localhost:8080/swagger-ui/ 혹은 http://localhost:8080/swagger-ui/index.html 을 통해 잘 접속되는지 확인한다. 

• swagger 3.0.0 버전 이하에서는 /swagger-ui.html 을 통해 제공되었지만 3.0.0 버전 이후로는 /swagger-ui/ 또는 /swagger-ui/index.html 을 통해 접근하도록 변경되었다. 

(분명히 처음에 /swagger-ui/ 을 통해 접근되는거 확인하고 오랜만에 다시켰는데 404 뜨면서 안돼서... clean 하고 2.9.2 버전으로 바꿔서 /swagger-ui.html 으로 접근해보고 했는데도 전부 404 나와서 정말! 이상한 삽질을 했다. 여러번의 clean 과 install 로 다시된다ㅠ 이럴때 너무 억울)