[SpringBoot] 스프링부트에 Swagger 설치하기

박진용·2023년 2월 1일

개인프로젝트를 하며 협업을 할때 필요한 API 문서화에 대한 필요성을 느꼈다.
나중에 실무에 적용하게 될 때를 위해 알게 된것을 정리해둔다.
프로젝트는 스프링부트로 진행하고 있어 스웨거 적용하기로 했다.

Swagger

스웨거는 사용자, 팀, 기업체를 위해 API개발을 단순화해주는 오픈소스이다.
실제로 위 사진처럼 다양한 툴을 지원하며, 오늘 기록하려고 하는건 이중 Swagger-UI를 적용하려고 한다.

Libary

스프링부트에 스웨거를 적용하기 위해서 오픈소스 라이브러리가 필요하다. 두 가지가 있는데
SpringFox와 SpringDoc이다.
간략하게 설명하면

SpringFox

Springfox는 2011경에 나온 스웨거를 지원하기 위해 2018에 출시되었다고 한다.
2015년에 처음 나와, 2018년에 업데이트가 중단되었고, 간간히 업데이트 되는 듯하나
지속적인 관리가 되고있는것 같지는 않다.

SpringDoc

SpringFox가 업데이트를 중단하고 나온 라이브러리이다. 최근까지도 지속적으로 업데이트를 하며
SpfingFox에서 불편했던 점들(그룹핑 등, 현재 Springfox에서도 그룹핑을 지원하는지는 모르겠다.)
을 추가 지원하며 현재는 주류가 되었다고 한다.

적용

그래서 이번 과제에는 SpringDoc을 이용해 Swagger를 사용해 보려고한다.

버전

개인적으로 진행하는 프로젝트이기 때문에 최신 버전의 스프링부트를 사용하고 있어
springdoc-openapi v2를 추가했다. (이전 버전이랑 dependency가 다르다)
아래 내용은 전부 v2로 진행했다. 이 부분때문에 조금 삽질이 있었는데 구글링시에 나오는
Docket 클래스를 사용하는 글들은 이전 버전용 이라서 실행시에 예상했던 동작결과와 조금 달랐다.

스프링부트 3.0 이상

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.0.2</version>
   </dependency>

참고: https://springdoc.org/v2/

스프링부트 3.0 이하

  <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.6.14</version>
   </dependency>

참고: https://springdoc.org/

코드

참조: 스프링독 깃헙(https://github.com/springdoc/springdoc-openapi)

@SpringBootApplication
public class SwaggerApplication {
  
  public static void main(String[] args) {
    SpringApplication.run(SwaggerApplication.class, args);
  }
  
  @Bean
  public GroupedOpenApi userGroup() {
    return GroupedOpenApi.builder()
      .group("user")
      .addOperationCustomizer(((operation, handlerMethod) -> {
        operation.addSecurityItem(new SecurityRequirement().addList("basicScheme"));
        return operation;
      }))
      .addOpenApiCustomizer(openApi -> openApi.info(new Info().title("Methods").version("v0.1")))
      .packagesToScan("com.springboot.swagger")
      .build();
   
  }
  
}

스프링독 깃헙에서 위 소스를 참고하였다.
그룹을 지원하는 코드로 "user" 그룹을 설정하는 코드이다.

addOperationCustomizer는 전역적인 설정을 담당하는 듯한데 이부분은 아직 공부가 부족한 것 같다.
위 코드에서는 보안관련 설정을 해주었고, 추후 이 부분에 설정을 통해 jwt등을 적용할 수 있을 듯 하다

addOpenApiCustomizer는 OpenAPI객체를 커스텀하여 타이틀과 버전등을 설정할수 있는 듯하다.
해당 부분을 설정하여 실행시키면 "서버주소/swagger-ui/index.html" 로 접속이 가능하다.

packagesToScan은 내 프로젝트 경로에서 스웨거가 읽어들일 패키지명을 적어두었다.

접속하면 다음과 같은 화면을 볼 수 있다.

오른쪽 위의 그룹에서 설정한 user그룹과 아래의 설정한 타이틀, 그리고 버전을 확인할 수 있다.

설정파일을 통해 적용

application.yml을 통해서도 그룹이나 패키지 경로등을 입력 할 수 있다.
application.yml에 properties를 통해 값을 설정 가능한다. 설정 가능한 properties에 대해서는
공식 문서의 properties 항목을 참조했다.

springdoc:
  swagger-ui:
    display-request-duration: true
    groups-order: DESC
    operations-sorter: method
    disable-swagger-default-url: true
    use-root-path: true
  show-actuator: true
  group-configs:
    - group: controller
      paths-to-match:
        - /api/v1/put-api/**
        - /api/v1/post-api/**

    - group: get-controller
      paths-to-match:
        - /api/v1/get-api/**

설정한 항목은 위와 같다.
가장 아래의 group-configs를 통해 그룹화가 가능하다.
group명을 적고 그룹화할 api주소를 적게 되면 다음 사진처럼 해당 경로와 일치하는 api들의 그룹화가 된다.