스프링 부트 3에 Swagger 적용하기
REST API 문서 도입기
최근 REST API 문서 생성을 위해 Swagger 도입을 고려하고 있었다. 그래서 구글링을 통해 Swagger 적용 방법에 대한 글을 찾아보고 그대로 적용해 보았다. 그런데 이게 웬걸? Swagger를 적용하고 접속해본 곳에는 오직 Whitelabel Error Page 만이 반겨줄 뿐이었다.
스택 오버플로우를 찾아도 스프링 부트 버전을 2.5.X으로 낮추라는 얘기만 할 뿐, 내가 원하는 답은 나오지 않았다. 이틀을 낭비하고 나서야, 내가 사용 하려던 Swagger 라이브러리가 최신이 아닌 지원 중단된 버전이라는 것을 알게 되었다.
Springdoc의 Swagger를 사용하자
Swagger는 본디 스프링 프레임워크만을 위한 REST API 문서 생성 도구는 아니다. Node.js의 Express나 Python의 Django같은, 개발자라면 누구나 알법한 웹 프레임워크 라면 대부분 사용 가능한 오픈소스 프로젝트다. 이 오픈소스를 스프링 프레임워크에서 사용할 수 있도록 개발하던 주체가 Springfox라는 그룹이다. 하지만 현재 이 그룹에서 개발하던 Swagger는 2020년 7월 이후로 개발이 중단 되었다. 따라서, 최신 버전의 스프링 부트 프레임워크에서는 정상적인 동작을 보증하기 어렵다. 실제로 Springfox의 Swagger는 스프링 부트 2.6.X 버전부터 정상적으로 동작하지 않는다는 증언 계속해서 나오고 있다.
사실 최신 버전의 스프링 부트 프레임워크 미지원 뿐만 아니라, 여러가지 최신 라이브러리 (특히 WebFlux)에 대한 지원도 미비했던 까닭에 2019년 부터 새로운 Swagger 라이브러리를 개발하는 Springdoc이라는 그룹이 발족하게 되었다. 따라서 최신 스프링 부트 프레임워크를 사용한다면 Springdoc의 Swagger를 쓰는 것을 권장한다.
Swagger 설정하기
Springdoc의 Swagger를 사용하려면 다음 의존성만 추가해주면 된다.
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.2.0</version>
</dependency>dependencies {
implementation'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'
}이전 버전과 달리 별도의 설정을 하지 않더라도, http://localhost:8080/swagger-ui/index.html에 접속하면 곧바로 REST API 문서를 볼 수 있다. 하지만, 조금 더 보기 좋도록 OpenAPI 빈 객체 생성하도록 하겠다.
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI openAPI() {
return new OpenAPI().info(
new Info().title("Your API Title")
.description("Your API Description")
.version("1.0")
);
}
}
Springfox Swagger와 달리, Springdoc Swagger는 스프링에서 제공하는 방식으로 REST API를 설계하기만 하면 자동으로 문서까지 모두 완성해주는 것을 볼 수 있다! 물론 일부 내용을 원하는 대로 커스텀 하기 위해 여전히 어노테이션을 지원하므로 이제는 개발자가 원하는대로 주무르기만 하면 된다.
/swagger-ui/**와 /v3/**를 추가해줘야 한다. 추가하지 않는다면, 401 Error Page나 아무것도 보이지 않는 swagger-ui 화면만 보이게 된다!Springfox 마이그레이션 하기
Springdoc Swagger는 Springfox Swagger 버전과 어노테이션이 다르다. 따라서 이전 버전용으로 작성된 어노테이션을 아래와 같이 바꾸어 주어야 정상 동작한다. 이는 아래의 공식 문서 9번 항목에 나와있는 내용이다.
@Api→@Tag@ApiIgnore→@Parameter(hidden = true)or@Operation(hidden = true)or@Hidden@ApiImplicitParam→@Parameter@ApiImplicitParams→@Parameters@ApiModel→@Schema@ApiModelProperty(hidden = true)→@Schema(accessMode = READ_ONLY)@ApiModelProperty→@Schema@ApiOperation(value = "foo", notes = "bar")→@Operation(summary = "foo", description = "bar")@ApiParam→@Parameter@ApiResponse(code = 404, message = "foo")→@ApiResponse(responseCode = "404", description = "foo")
정리하며
REST API 방식으로 개발하면서 한번 쯤은 꼭 자동 문서화를 시키고 싶었는데, 이번 기회에 수 많은 삽질을 해대면서 적용하고 정리해 보았다. 나처럼 스프링 부트 3에서 Swagger를 적용하면서 수 많은 삽질을 시도한 사람들에게 도움을 줄 수 있길 바라면서 이 글을 마치도록 하겠다.