(swagger3)springdoc 설정 (feat.spring security 6)

목표

spring boot, spring security 환경에서 springdoc을 붙여보자

 

1. 들어가기 앞서 api 문서란 무엇인가? 

어떤 url을 통해 api 요청을 보낼 수 있는지 그리고 해당 api에 어떤 값들을 요청을 해야하는지, 해당 api로 부터 어떤 응답값이 내려오는지 등을 정리한 문서이다. 

 

2. 그럼 springdoc은 무엇인가?

springdoc은 당신이 만든 api를 자동으로 문서화 해주는 역할을 하는 친구이다. 쉽게 예시를 들어보자 

spring mvc 환경에서 개발자가 controller class를 작성하고 url 매핑값을 지정하고 응답값은 string을 내려주는 메소드를 작성했다. 그럼 springdoc에서 제공하는 어노테이션들을 추가해서 설정을 하면 swagger-ui를 통해 해당 클래스의 정보와 메소드들의 응답값, 요청 파라미터 등을 문서로 볼 수 있다. 

 

3. 그렇다면 왜 필요한가?

지극히 개인적인 생각이지만 만약 문서화를 자동으로 해주는 라이브러리가 없다고 하면 개발자는 직접 작성 해야한다. 즉 워드 문서 열고~ 버전 명시하고~ 작성자 땡땡땡 하고 url 하나씩 복붙해서 응답값은 이렇고 요청값은 이렇다 등을 직접 다 작성해야 하는 상황이 발생한다. 

하지만 자동으로 문서화를 해버리면 저런 쓸데없는 시간을 세이브할 수 있고 그 시간에 다른 생산적인 것들을 더 할 수 있다. 개발이 되든 다른 사업을 추진하든 뭐든 할 시간이 생기는거다. 또한 api 관리가 좀 더 수월해진다는 장점도 있다. 

1. 환경

다음은 필자의 환경이다 참고하자. 대부분 그냥 최신 버전 쓴다... 

 

1.spring boot 3.0.5

2.spring security

3.gradle

4.Java 17

 

이정도다. 

 

2. build.gradle 라이브러리 추가

필자는 아무생각없이 swagger3를 검색해서 아무 글이나 들어가서 springdoc-openapi-ui 라이브러리를 추가했었다. 

 

But!!!!!!!!!!!!실행 시키고 나면 계속 404가 난다 설정 다 해주고 했는데도...그래서 뒤적뒤적 공식문서도 보고 하다가 해당 라이브러리를 받아서 했다. 스프링 시큐리티도 같이 추가해주자.

 

참고로 2.10까지 나온 것으로 알고 있으며 공식 문서는 https://springdoc.org/v2 해당 링크로 이동하면 된다.

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.4'
implementation 'org.springframework.boot:spring-boot-starter-security'

 

3. application.yml 설정 추가

properties파일로 설정해도 무관하며 해당 글에서는 yml 파일로 작성했다. 다른 이유는 없고 그냥 보기 더 편해서 yml로 작성했다

springdoc:
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  swagger-ui:
    groups-order: DESC
    disable-swagger-default-url: true
    display-request-duration: true
    operations-sorter: method
    path: /swagger-ui.html
    enabled: true
  api-docs:
    path: /api-docs

모든 설정을 설명드리고 싶지만 더 자세하게 설명해줄 공식문서를 참고하자 친절하고 자세하게 설명이 다 나와있다.

https://springdoc.org/#properties

OpenAPI 3 Library for spring-boot

4. OpenApiConfig 

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI openAPI() {
        Info info = new Info()
                .version("v1.0.0")
                .title("테스트")
                .description("API Description");

        return new OpenAPI().components(new Components())
                .info(info);    
    }
}

configuration 어노테이션을 통해 openApi에 대한 설정을 해주자.

5. spring security 설정

참고로 security 버전은 6이다. 

 

@Configuration
@EnableWebSecurity
public class SecurityConfig {
	
    private final JwtTokenProvider tokenProvider;
    private final JwtAuthenticationEntryPoint jwtAuthenticationEntryPoint;
    private final JwtAccessDeniedHandler accessDeniedHandler;

    public SecurityConfig(JwtTokenProvider tokenProvider, JwtAuthenticationEntryPoint jwtAuthenticationEntryPoint, JwtAccessDeniedHandler accessDeniedHandler) {
        this.tokenProvider = tokenProvider;
        this.jwtAuthenticationEntryPoint = jwtAuthenticationEntryPoint;
        this.accessDeniedHandler = accessDeniedHandler;
    }

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.csrf().disable();
        http.sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)
                .and()
                    .cors()
                .and()
                .httpBasic().disable()
                .formLogin().disable()
                .authorizeHttpRequests()
                .requestMatchers(
                        "/swagger-ui.html",
                        "/swagger-ui/**",
                        "/v3/api-docs/**",
                        "/api-docs/**").permitAll()
                .anyRequest().authenticated()
                .and()
                .exceptionHandling()
                    .authenticationEntryPoint(jwtAuthenticationEntryPoint)
                    .accessDeniedHandler(accessDeniedHandler)
                .and()
                .apply(new JwtSecurityConfig(tokenProvider));

        return http.build();
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}

해당 코드에서 다른 부분은 제외하고 아래 설정 부분이 swagger-ui를 접근을 허용해주는 부분이다.

.authorizeHttpRequests()
.requestMatchers(
        "/swagger-ui.html",
        "/swagger-ui/**",
        "/v3/api-docs/**",
        "/api-docs/**").permitAll()

6. Test Controller 작성 

@RestController
@RequestMapping("/api")
@Tag(name = "test controller", description = "test controller")
public class TestController {

    private final static Logger logger = LoggerFactory.getLogger(TestController.class);

    private final TestApiService testApiService;

    public TestController(TestApiService testApiService) {
        this.testApiService = testApiService;
    }

    @Operation(summary = "test method", description = "테스트 메소드")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = RestApiResponse.class))),
            @ApiResponse(responseCode = "400", description = "BAD REQUEST"),
            @ApiResponse(responseCode = "404", description = "NOT FOUND"),
            @ApiResponse(responseCode = "500", description = "INTERNAL SERVER ERROR")
    })
    @GetMapping(value = "/test/v1")
    public String test(String name) {
        logger.info("TestController.test()");
        return "test + " + name;
    }

    @PostMapping(value = "/test/v2")
    public String test_ver2(@RequestBody String name){
        logger.info("name =============== {}", name);
        // testServiceApi.throwExceptionFunc();
        return "test_ver2 " + name;
    }
}

springdoc에서 지원하는 주요 어노테이션들은 @Tag, @Operation, @ApiResponses, @ApiResponse 등이 있다. 

해당 어노테이션들이 어떤 역할을 하는지는 swagger2와 3를 참조해보면 알 수 있다. 

 

참고로  https://springdoc.org/v2/#migrating-from-springfox

springdoc-openapi v2.1.0

위 링크로 들어가면 swagger2에서 사용하던 어노테이션이 3에서 무엇으로 바뀌었는지 알 수 있으며 swaager2 공식문서를 가면 각 어노테이션에 대한 설명들이 자세하게 나와있다. 

7. swagger-ui 확인

이제 swagger-ui로 확인해보자

접속은 http://localhost:8080/swagger-ui/index.html로 접속할 수 있다. 그럼 아래 사진과 같이 뜰 것이다.

아까 작성한 test controller도 잘 뜬다.