API 문서 자동화 - Swagger

Spring REST Docs와 마찬가지로 API 문서 자동화해주는 Swagger라는 기술을 소개하려고 합니다.

 

[제가 알기로는] Spring을 사용하면서 API 문서 자동화를 제공하는 기술은 대표적으로 Spring REST Docs와 Swagger가 있습니다. 오늘은 그중 하나인 Swagger라는 기술에 대해 소개하려고 합니다.

 

※ Spring REST Docs의 사용 방법을 확인하시려면 아래 페이지를 참고해주세요.

2021.11.27 - [Spring] - API 문서 자동화 - Spring REST Docs

 

Swagger를 소개하기에 앞서 Spring REST Docs와 Swagger 각각의 장단점을 알아봅시다. 그리고 상황에 맞는 기술을 사용하면 될 것 같습니다.

	Spring REST Docs	Swagger
장점	서비스 코드에 영향을 주지 않는다.	간편하게 적용할 수 있다.
	테스트가 성공해야 문서를 만들어준다.	문서 내에서 API를 테스트할 수 있다.
단점	적용하기 어렵다.	서비스 코드에 어노테이션을 추가해야한다.
	테스트 코드 작성을 필수로 요구한다.	문서만으로 연동 시스템을 만들기 어렵다.

 

현재 대 HTTP 시대가 도래하면서 RESTful API를 사용하여 서버와 SPA(react, vue) 프레임워크, 모바일(Android, iOS) 사이에서 데이터를 주고받는 구조가 많은 회사에 자리 잡았습니다. 그런데 이런 구조로 개발, 유지보수를 진행하다 보면 해당 서버가 제공하는 API 스펙이 어떤지에 대해서 쉽게 알 수 있도록 문서 작업이 꼭 필요합니다. [큰 회사나 규모가 있는 프로젝트는 API가 정말 많을 테니깐요.]

하지만 이런 문서 작업은 개발자를 귀찮게 하고 [개발자는 귀찮은 거 정말 싫어하죠..], 또 기능이 추가되거나 변경이 될 때마다 추가적으로 작업을 해야 하다 보니 Spring REST Docs나 Swagger와 같은 API 스펙 문서를 자동화하는 기술이 나오게 되었습니다.

 

그럼 Swagger를 적용하는 방법에 대해서 알아보겠습니다. 

 

프로젝트 버전

• 개발 도구: IntelliJ Ultimate
• Spring Boot: 2.5.7
• Java 11
• Spring Web 의존성 추가 [build.gradle]

 

첫 번째로, Swagger를 사용하기 위한 의존성 2개를 추가해줍니다.

 

build.gradle

// build.gradle
dependencies {
   implementation 'io.springfox:springfox-swagger2:3.0.0'
   implementation 'io.springfox:springfox-swagger-ui:2.9.2'
}

 

• [swagger2]를 사용할 것입니다.
• [swagger-ui] - API 문서를 이쁘게 보여주는 의존성을 추가합니다.

 

두 번째로, Swagger를 애플리케이션에 적용하기 위한 설정 클래스를 만들어줍니다.

 

SwaggerConfig

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket swaggerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("WangTak")
                .apiInfo(apiInfo())
                .select()
                .paths(PathSelectors.ant("/api/**"))
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("WangTak")
                .description("WangTak API Test for Swagger Documentation")
                .termsOfServiceUrl("https://wangtak.tistory.com")
                .license("WangTak")
                .licenseUrl("https://wangtak.tistory.com").version("1.0").build();
    }
}

 

세 번째로, 문서화시킬 2개의 Controller를 만들어줍니다.

 

MemberController

// MemberController
@Slf4j
@RestController
public class MemberController {

    @GetMapping("/api/test")
    @ApiOperation(value = "멤버 반환 테스트", response = Member.class)
    public ResponseEntity<Member> apiTest() {
        log.info("HomeController API Test");
        return ResponseEntity.ok(new Member("wangtak@gmail.com", "왕탁이", "ㄱㄱㄱ시 ㄴㄴㄴ동"));
    }

    @PostMapping("/api/members")
    @ApiOperation(value = "멤버 저장 테스트", response = Member.class)
    public ResponseEntity<Member> addMember(Member member) {
        log.info("Member Information : {}", member);
        return ResponseEntity.ok(member);
    }

    @GetMapping("/test")
    @ApiOperation(value = "멤버 반환 테스트", response = Member.class)
    public ResponseEntity<Member> test() {
        log.info("HomeController Test");
        return ResponseEntity.ok(new Member("wangtak@gmail.com", "왕탁이", "ㄷㄷㄷ시 ㄹㄹㄹ동"));
    }
}

 

HomeController

// HomeController
@Slf4j
@RestController
public class HomeController {

    @GetMapping("/api")
    public String index() {
        return "HOME";
    }
}

 

필요한 준비물은 모두 끝났습니다. 애플리케이션을 실행하고 확인해보겠습니다.

• Json API Doc URL: localhost:8080/v2/api-docs?group=groupName
• Swagger UI URL: localhost:8080/swagger-ui.html

 

Swagger UI

Swagger UI

• 위 3개의 빨간 박스는 SwaggerConfig에 있는 apiInfo()와 매칭 해보면 이해하시기 쉬울 것 같습니다.
• API 목록은 Controller에 따라 구분이 됩니다.
• API에서 사용하는 Model(Member)에 대한 Spec도 확인할 수 있습니다.
• 분명히 API는 4개 만들었습니다. HomeController 1개, MemberController 3개. 근데 3개만 나오는 이유는 SwaggerConfig에서 PathSelectors.ant("/api/**")를 설정하였기 때문에 /api로 시작하는 api만 문서화하도록 한 것입니다.

 

문서화를 해봤으니 Swagger의 장점인 문서에 있는 API 테스트를 해보도록 하겠습니다. 테스트할 API는 [POST] /api/members입니다.

 

1. 테스트를 원하는 API를 클릭하고, 우측 상단에 있는 "Try it out" 버턴을 클릭합니다.

테스트를 원하는 API를 클릭했을 때 나오는 화면

 

2. 생성된 Input Box에 API를 호출하기 위한 테스트 데이터를 입력합니다. 그런 후에 "Execute" 버튼을 누릅니다.

테스트 데이터 입력

 

3. 그러면 다음과 같이 API가 실행됩니다. 해당 API에 남겨뒀던 로그에 값이 찍혀있으며, Response Body에는 저희가 테스트했던 값이 그대로 반환되는 것을 확인할 수 있습니다.

 

/api/members Controller Log 기록

테스트로 입력했던 데이터가 그대로 반환

 

정리

지금까지 API 문서를 자동화해주는 Swagger에 대해 정리해봤습니다. 2가지 모두 사용해본 저로써는 위에서 정리한 장단점이 와닿았고 직접 체감이 되었습니다. 특히, Spring REST Docs를 적용하기 위한 시간이 많이 들었답니다..! 그래도, 개인적으로는 테스트 코드를 반강제적(?)으로 작성하게 해주는 Spring REST Docs가 좋은 거 같습니다.