[Spring] Swagger 3.0 적용

Swagger는 REST API의 문서화, 테스트를 용이하게 해주는 프레임워크이다.

나같은 경우는 백엔드 개발을 하면서 API들을 직접 문서화시켜서 다른 개발자들과 공유하곤 했는데, Swagger를 사용하면 개발과 동시에 자동으로 문서화를 시켜주기 때문에 요즘 유용하게 사용하고 있는 도구이다.

특히, Spring에서는 애노테이션을 통해 더 편리하게 Swagger를 사용할 수 있는데, 지금부터 해당 방법을 소개한다.

 

라이브러리 추가

먼저 Swagger 사용을 위해 구현체인 springfox 라이브러리를 추가한다.

dependencies {
   ...
   implementation 'io.springfox:springfox-boot-starter:3.0.0'
}

 

 

SwaggerConfig

Swagger를 위한 설정 파일을 만든다.

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .additionalModels(typeResolver.resolve(MemberResponseDto.class))
                .additionalModels(typeResolver.resolve(ErrorResponse.class))
                .useDefaultResponseMessages(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Backend API")
                .description("Backend API 문서")
                .version("1.0")
                .build();
    }
}

 

따로 설정할 부분은 basePackage에 본인이 Swagger로 문서화하길 원하는 패키지(일반적으로 controller)를 지정하고,
apiInfo()에 원하는 제목, 설명, 버전을 적으면 된다.

+) additionalModels(typeResolver...) 부분은 내가 임의로 만든 클래스를 response type으로 지정하기 위해서 추가한 부분으로 이후에 설명하겠다.

 

Swagger 웹페이지

이제 프로젝트를 실행하고 다음 URL로 접속하면 swagger 페이지를 볼 수 있다.

http://localhost:8080/swagger-ui/index.html

꼭 localhost:8080이 아니어도, 본인의 프로젝트가 실행되는 IP 주소에서 "/swagger-ui/index.html" 을 붙이면 접속할 수 있다.

다음과 같은 페이지가 보이면 접속에 성공한 것이다.

 

 

 

+) 만약 프로젝트 실행시 documentationPluginsBootstrapper 빈 생성에 실패했다는 오류가 뜬다면 application.yml에 다음 설정을 추가해주자. spring boot 2.6 부터 matching-strategy의 default 값이 ant_path_matcher -> path_pattern_parser로 변경되서 생기는 이슈라고 한다.

spring:
    mvc:
      pathmatch:
            matching-strategy: ant_path_matcher

 

 

API 추가

이제 controller 디렉토리에 컨트롤러와 API를 추가해보자.

@RestController
@RequestMapping("/members")
public class MemberController {

    @GetMapping("{id}")
    public String get(@PathVariable String id) {
        return id;
    }
}

 

다시 프로젝트를 실행시켜 보면 API가 하나 추가된 것을 볼 수 있다.

 

 

 

Pathvariable을 입력하는 부분과 Response를 보여주고 있다. API에 특별한 설정을 하지 않으면 위와 같이 200 response만 기본적으로 보여준다.

 

Swagger에서는 Postman 처럼 실제로 API를 테스트해볼 수 있다.

우측 상단에 "Try it out"을 누르면 Pathvariable을 입력할 수 있게 되고, 아래 "Execute"를 누르면 결과를 확인할 수 있다.

 

 

Pathvariable에 1을 집어넣고 실행시켰다. 정상적으로 Response에 1이 담겨 있는 것을 확인할 수 있다. Response body 뿐만 아니라 Header 값도 보여주고 있다.

 

Swagger 꾸미기

이제 진짜 API 명세서 답게 API에 대한 설명과 Response 형식들을 Swagger에 추가해보자.

컨트롤러의 API를 명세가 잘 되도록 수정했다.

@RestController
@RequestMapping("/members")
@RequiredArgsConstructor
@Tag(name = "Members", description = "Member API")
public class MemberController {

    private final MemberService memberService;

    @Tag(name = "Members")
    @GetMapping("{id}")
    @Operation(summary = "회원 조회", description = "id에 해당하는 회원을 조회한다.", responses = {
            @ApiResponse(responseCode = "200", description = "성공", content = @Content(schema = @Schema(implementation = MemberResponseDto.class))),
            @ApiResponse(responseCode = "400", description = "실패 - id에 해당하는 회원이 없음", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
    })
    public MemberResponseDto get(@Parameter(description = "회원 id") @PathVariable Long id) {
        Member member = memberService.findById(id);
        return new MemberResponseDto(member.getId(), member.getName());
    }
}

 

이처럼 여러가지 애노테이션으로 쉽게 Swagger 설정을 할 수 있다.

1. @Tag: 화면에서 보이는 API 그룹의 이름을 지정할 수 있다. @Tag가 같은 API끼리 패키지 처럼 한 그룹에 포함된다.

2. @Operation: API 별로 간단한 설명을 추가할 수 있다. @ApiResponse를 통해 반환 타입도 설정할 수 있다.

3. @ApiResponse: 반환 타입을 설정할 수 있다. status code와 간단한 설명 그리고 해당 status code에 대한 반환 클래스를 지정할 수 있다. MemberResponseDto와 ErrorResponse 내가 임의로 만든 클래스이다. (SwaggerConfig에 typeResolver 속성으로 부여한 클래스)

 

적용된 화면은 다음과 같다.

 

 

 

 

코드상으로 수정하기 전후 API를 비교해가며 Swagger의 변경점을 파악해보자. 참고로 Response body는 지정한 반환 클래스의 껍데기만 볼 수 있다. 실제 어떤 값이 들어가서 Response되는지 보고 싶다면 아까처럼 "Try it out"을 클릭하고 테스트해보면 된다.

 

---

 

Swagger에 대한 더 자세한 설정은 관련 문서를 참고하자. 여기서 중요한 것은 Spring이 제공하는 애노테이션을 통해 간단하게 Swagger 설정을 할 수 있다는 것이다.

 

참고자료

https://blog.jiniworld.me/91