Spring Boot 프로젝트에 Swagger 적용하기 (+인증)

안녕하세요. 유저인사이트 박태양입니다.
이번 시간에는 Spring Boot 프로젝트에 Swagger를 적용하는 방법을 알아보겠습니다.

Swagger는 API 개발 및 문서화를 도와주는 오픈소스 프레임워크입니다.
여러분이 생성한 API를 자동으로 문서화 해주고, 웹 페이지를 통해 편리하게 호출할 수 있습니다.

 

---

실습 버전 정보는 아래와 같습니다.
Spring Boot : 2.7.9
Java : 11 (JDK 11.0.2)
Swagger : 3.0.0

Swagger 사용을 위해 pom.xml에 아래 디펜던시를 추가해줍니다.

SpringFox는 Spring 기반으로 개발된 API를 자동으로 문서화 해주는 역할을 합니다.

 

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

Swagger 관련 설정을 담당할 Config 파일을 생성합니다.

 

@Configuration
public class SwaggerConfig {

  public static final String AUTHORIZATION_HEADER = "Authorization";

  @Bean
  public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2).securityContexts(
            Arrays.asList(securityContext())).securitySchemes(Arrays.asList(apiKey())).select()
        .apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build();
  }

  private ApiKey apiKey() {
    return new ApiKey("JWT", AUTHORIZATION_HEADER, "header");
  }

  private SecurityContext securityContext() {
    return SecurityContext.builder().securityReferences(defaultAuth()).build();
  }

  List<SecurityReference> defaultAuth() {
    AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
    AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
    authorizationScopes[0] = authorizationScope;
    return Arrays.asList(new SecurityReference("JWT", authorizationScopes));
  }
}

 

securityContexts : API 작업에 사용할 기본 인증 방식 목록

securitySchemes : 스웨거에서 사용할 API 인증 방식 목록

apis : API 컨트롤러 패키지 경로

paths : 패키지 내 API 경로

 

간단한 테스트를 위해 컨트롤러를 추가합니다.

 

@RestController(value = "/user")
public class UserController {

  @GetMapping
  public List<String> list() {
    return Arrays.asList("Junho Park, Jinyong Park");
  }
}

 

Spring Boot 2.6 부터 pathmatch 기본값이 변경되었습니다. (AntPathMatcher -> PathPatternParser)

PathPattern에서는 ** 형식이 마지막에서만 사용 가능합니다.

예) /pages/{**} (가능) /pages/{**}/details (불가능)

그래서 application.yml에서 아래와 같은 설정 값 추가가 필요합니다.

 

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

 

앱 실행 후 http://localhost:8080/swagger-ui/ 로 접속하면 아래와 같은 화면을 볼 수 있습니다.

 

 

기존에 CRUD 관련 API를 생성해 두었다면, 아래와 같이 메서드별로 정리되어 나타납니다.

 

 

인증토큰을 헤더에 추가하면 아래와 같이 요청됩니다.

 

 

만약, 운영서버에서 스웨거 UI를 숨기고 싶다면, application.yml 파일에서 아래와 같이 설정해주면 됩니다.

 

springfox:
  documentation:
    enabled: false

 

---

이상으로 Spring Boot 프로젝트에 Swagger 세팅하는 방법을 알아보았습니다.

감사합니다.

참고자료 : https://github.com/eugenp/tutorials/tree/master/spring-security-modules/spring-security-web-rest