springboot3.x + swagger API 적용하기(spring security 사용)

spring boot로 로직 서버를 작성하던 중 API 명세를 작성해야 하는 일이 많았다.

기존에는 notion으로 작성했지만, 변경사항이 있을 때 마다 code 이외의 추가 수정이 필요해 팀원들과 상의 후 swagger을 적용해 보고자 했다.

---

spring boot 버전 정보

plugins {
	id 'java'
	id 'org.springframework.boot' version '3.2.5'
	id 'io.spring.dependency-management' version '1.1.4'
}

 

 

 

Springfox가 Spring Boot 3.x에서 지원하지 않아 SpringDoc 라이브러리를 사용하는 것을 권장한다.

 

(Spring Boot 2.x버전이라면 Spring fox를 사용하는 것이 더 호환성이 좋다고 한다.(기존 정보도 더 많고))

 

Springfox swagger의 경우 2020년 7월 업데이트 이후 후속 업데이트가 없는 것을 보아 프로젝트 특성에 잘 고려 후 사용하면 좋을 것 같다.

 

Springdoc-openapi 관련 설정 yml 추가

dependencies{
//swagger 관련 설정
	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'
}

 

최신 버전을 확인하고 싶으면 공식문서를 참고하면서 하면 좋을 것 같다.

 

->springdoc 공식문서

https://springdoc.org/

 

Spring security 설정

springdoc공식 문서에 따르면 위의 설정 후 Swagger UI 페이지가 이용 가능해 진다. 

 

http://server:port/context-path/swagger-ui.html

server -> 서버 이름 또는 IP(별도 설정 X 경우 localhost)
port -> port 번호

 

하지만 필자의 프로젝트는 spring security 권한 설정으로 인해 401에러가 발생했다.

 

 

 

이로 인해 추가 설정을 진행하였다.

swagger.yml 파일 추가

# Swagger
springdoc:
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  api-docs:
    groups:
      enabled: true
  swagger-ui:
    operations-sorter: alpha # 정렬기준
    tags-sorter: alpha # 태그정렬기준
    path: /swagger
    disable-swagger-default-url: true
    display-query-params-without-oauth2: true
    doc-expansion: none
  paths-to-match:
    - /**  #애플리 케이션의 모든 api(엔드포인트)

 

 

반드시 resource하위에 넣어 주어야 한다

(기존 application.yml이 존재했지만 편의를 위해 분리해서 작성했다.)

 

SwaggerCongfig 파일 추가

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {

        Info info = new Info()
                .version("v1.0.0")
                .title("졸업프로젝트(demo_book) API")
                .description("졸프 spring logic API 목록입니다.");

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

 

ui 편의를 위해 config 파일을 새로 생성한 후 추가해 주었다.

 

 

기존 SecurityConfig 코드 추가

마지막으로 security config 부분에 코드를 추가하였다.

 @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
        
        //기존 부분에 추가
                   .authorizeHttpRequests(authorizeHttpRequests -> authorizeHttpRequests
                        .requestMatchers("/swagger", "/swagger-ui.html", "/swagger-ui/**", "/api-docs", "/api-docs/**", "/v3/api-docs/**")
                        .permitAll()
                        .requestMatchers("/api/hello", "/api/authenticate", "/api/signup").permitAll()//위 부분은 허용
                        .requestMatchers(PathRequest.toH2Console()).permitAll()
                        .anyRequest().authenticated()//나머지 요청들은 모두 인증을 받아야 한다
                )

 

 

 Swagger와 관련된 모든 URL 경로를 지정하였다.

여기서 다루는 경로들은 Swagger UI와 OpenAPI 문서에 접근하기 위해 사용되는 경로들이다.

(인증 없이 접근을 허락하기 위해)

 

결과

 

그 후 server을 실행 후 아까 url로 접속해보면

 

 

 

잘 적용 된 것을 확인할 수 있다.