케이스윔의 개발 블로그

Swagger 설정하기 본문

Study/Spring Framework

Swagger 설정하기

kswim 2021. 7. 10. 22:43
 

OpenAPI Specification - Version 3.0.3 | Swagger

OpenAPI Specification Version 3.0.3 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC2119 RF

swagger.io

 

Setting Up Swagger 2 with a Spring REST API | Baeldung

Learn how to document a Spring REST API using Swagger 2.

www.baeldung.com

 

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 로 다시된다ㅠ 이럴때 너무 억울)

 

Comments