Spring boot에 Swagger ui 적용기

Swagger 적용한 이유

Swagger는 자바 API 문서를 자동으로 생성해주는 오픈소스 도구 세트이며

API 를 테스트 해 볼수 있는 화면을 제공하고 쉽게 적용해 볼 수 있어 사용해보았다.

테스트하기 쉽게 밥상을 차려주기 때문에

파일도 쉽게 테스트 할 수 있고, 데이터 입력해서 excute 해보면 결과 확인 해 볼 수 있음

 

프론트와 백엔드가 소통하는데 자바 API 문서를 주고 받을 수 있고

코드를 변경할 때마다 문서를 작성하는 것은 번거로운 일인데 자동으로 적용해주며

명세화면에서 요청을 보내면 응답 결과를 확인해 볼 수 있다.

 

baeldung docs 참고해서 적용해보기

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

 

1. gradle 의존성 추가

implementation 'io.springfox:springfox-swagger2:2.9.2'
implementation 'io.springfox:springfox-swagger-ui:2.9.2'

 

2. 자바설정 파일

basePackage와 paths에 나의경로를 적어주었다.(필수)

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.
                        basePackage("com.dddn.DDDnyang.controller"))
                .paths(PathSelectors.ant("/api/**")).build();
    }

}

Docket 빈을 정의한 후 해당 select() 메서드는 Swagger에 의해 노출된 끝점을 제어하는 ​​방법을 제공하는 ApiSelectorBuilder 인스턴스를 반환합니다 .

RequestHandlerSelectors 및 PathSelectors 의 도움으로 RequestHandler 를 선택하기 위한 술어를 구성할 수 있습니다 . 둘 다에 대해 any() 를 사용하면 Swagger를 통해 전체 API에 대한 문서를 사용할 수 있습니다. (baeldung docs 4.1)

 

3.  2.6이상부터 바뀌어서 필요하다고 한 설정

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

 

4. swagger ui 실행

경로설정에서 조금 헤맬수도 있긴 하지만 적용하기 쉬운 편인 것 같다.

http://localhost:8080/swagger-ui.html

(기본은 8080이고 나는 8090포트 사용했다)

---

추가설정 1) Docket 여러개 생성해보기 (groupName으로)

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket apiV1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("groupName1")
                .select()
                .apis(RequestHandlerSelectors.
                        basePackage("com.dddn.DDDnyang.controller"))
                .paths(PathSelectors.ant("/api/**")).build();
    }

    @Bean
    public Docket apiV2(){
        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .groupName("groupName2")
                .select()
                .apis(RequestHandlerSelectors.
                        basePackage("com.dddn.DDDnyang.controller"))
                .paths(PathSelectors.ant("/posts/**")).build();
    }
}

groupName1, 2를 선택할 수 있게 되었다.

 

추가설정 2) 시큐리티  사용시 설정해보기

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    private static final String[] SWAGGER_WHITELIST = {
            "/v3/api-docs/**",
            "/swagger-ui/**",
            "/swagger-ui.html",
    };

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
                .cors()
                .and()
                .authorizeRequests()
                .antMatchers(SWAGGER_WHITELIST).permitAll()
                .anyRequest().authenticated()
                .and()
                .httpBasic();
    }
}

SWAGGER_WHITELIST에 허용해주는 url을 입력해주고 아래 설정에서 허가 권한을 주어 들어갈 수 있게 되었다.

 

비밀번호 필요하다 해서 아래의 내용을 xml파일에 임시로 추가했으며 설정한대로 입력하면 화면을 보여준다.

spring.security.user.name=spring
spring.security.user.password=spring

 

---

+ 추가 (23.03.21) 🍪  쿠키 인증 🍪

swagger 2.0은 쿠키 인증을 지원하지 않는다.

로그인에 세션 쿠키를 주고 받아야 해서 3.0으로 업그레이드 시켜 주었다.

1. gradle 의존성 변경

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

2. configuration 에 버전 변경

(DocumentationType.SWAGGER_2  =>  DocumentationType.OAS_30)

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors
                        .basePackage("kr.rebe.deal.controller"))
                .paths(PathSelectors.ant("/**"))
                .build();
    }
}

 

 

swagger ui 쿠키와 관련된 내용 참고

Cookie Authentication