[spring boot] swagger 적용

gradle

compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'

SwaggerConfig

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean  // Docket : Swagger 설정의 핵심이 되는 Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.pmc.market"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }


    private ApiInfo apiInfo() {
        return new ApiInfo(
                "PMC Second Project",
                "Market - Consumer Rest API",
                "1.0.0",
                null, null, null, null,
                new ArrayList<>()
        );
    }
}

Docket 체이닝 메서드

http://springfox.github.io/springfox/javadoc/2.9.2/springfox/documentation/spring/web/plugins/Docket.html

• useDefaultResponseMessage()
  • false로 설정하면 swagger에서 제공해주는 응답코드(200, 401, 403, 404)에 대한 기본 메세지를 제거한다.
  • 불필요한 응답코드와 메세지를 제거하기 위함
• groupName()
  • Docket Bean이 1개이면 생략가능
  • Docket Bean이 2개 이상일 경우
    • groupName이 충돌하지 않아야 하므로 각 Docket Bean의 버젼을 명시하는 등 이름을 설정해 준다.
• select()
  • ApiSelectorBuilder를 생성한다.
• apis()
  • api 스펙이 작성되어 있는 패키지를 지정
  • 컨트롤러가 존재하는 패키지를 basepackage로 지정하며 RequestMapping이 선언된 API를 문서화 한다.
• paths()
  • apis()로 선택되어진 API중 특정 path 조건에 맞는 API들을 다시 필터링해 문서화 한다.
• apiInfo()
  • 제목, 설명 등 문서에 대한 정보들을 보여주기 위해 호출한다.

Controller에서 사용 방법

@Api(value = "MainController", tags = "메인 컨트롤러")
@RestController
@RequestMapping("/common")
public class MainController {

    // swagger 예제
    @ApiOperation("메인 ")
    @GetMapping("/{id}")
    public String mainTest(@ApiParam(value="id 같은 것") @PathVariable(value = "id")long id){
        String result = "hi"+String.valueOf(id);
        return result;
    }
}

@Api

• 해당 클래스가 Swagger 리소스라는 것을 명시한다.
• value : 태그 값
• tags : 여러개의 태그를 명시 할때

@ApiOperation

• 한 개의 operation(=API URL과 method)를 선언한다
• value : API에 대한 간략한 설명(제목) 작성
• notes : 더 자세한 설명

@ApiResponse

• operation의 가능한 response를 명시
• code : 응답코드 작성
• message : 응답에 대한 설명 작성
• responseHeaders : 헤더 추가 가능

@ApiParam

• 파라미터에 대한 정보 명시
• value : 파라미터 정보 작성
• required : 필수면 true, 아니면 false
• example : 테스트 할 때 보여줄 예시 작성

response를 글로벌 메시지로 설정하는 방법

swaggerConfig 파일에서 globalResponseMessage를 추가 해준다.

    @Bean 
    public Docket docket() {
		List<ResponseMessage> responseMessages = new ArrayList<>();
		    responseMessages.add(new ResponseMessageBuilder()
		            .code(200)
		            .message("OK ~~")
		            .build());
		    responseMessages.add(new ResponseMessageBuilder()
		            .code(404)
		            .message("Not Found ~~")
		            .build());
		    responseMessages.add(new ResponseMessageBuilder()
		            .code(500)
		            .message("Internal Server Error ~~")
		            .build());
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.pmc.market"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo())
								.globalResponseMessage(RequestMethod.GET, responseMessages);
    }

참고 https://victorydntmd.tistory.com/341

 

Security 적용시

swagger 관련 주소들을 무시해주는 설정을 추가한다.

@RequiredArgsConstructor
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.csrf().disable().headers().frameOptions().disable()
                .and()
                .authorizeRequests()
                .antMatchers("/", "/css/**", "/images/**", "/js/**", "/shops/**").permitAll()
                .anyRequest().authenticated()
                .and()
                .logout()
                .logoutSuccessUrl("/");
    }

    @Override
    public void configure(WebSecurity web) throws Exception {
        web.ignoring().antMatchers("/v2/**", "/configuration/ui", "/swagger-resources/**",
                "/configuration/security", "/swagger-ui.html/**", "/webjars/**", "/swagger**");
    }
}

참고  

https://ahea.wordpress.com/2017/01/18/spring-boot-swagger-적용기/

https://jamong-icetea.tistory.com/373

 

노션