Swagger를 사용하여 API 문서 자동화하기

곧 사이드 프로젝트 개발을 시작할 예정이다. 프로젝트를 진행하면서 Restful API에 대한 문서화를 자동으로 해주는 도구인 Swagger를 사용할 예정인데 Swagger 사용법에 대해 미리 정리해두고자 글을 작성한다.

Swagger

일반적으로 개발을 진행할 때, 백엔드 개발자와 프론트엔드 개발자로 역할이 나뉘고 두 개발자 사이에서 어떠한 방식으로 데이터를 주고 받을 지 명세가 필요하다. 이를 문서화 한게 API 명세서이며, 프로젝트 규모가 커질수록 API 명세서는 필수이다. Swagger는 Swagger Hub를 제공하며, 이를 통해 Open API를 사용해서 API를 정의하고, 관리할 수 있으며, 여러 개발자가 Swagger Hub를 통해 하나의 프로젝트에 대한 API를 작성하고 테스트 할 수 있다.

(기존에 Postman을 사용하여 API 테스트를 진행했었는데, 간단한 테스트는 Swagger에서 제공하는 테스트를 이용하면 편할 것 같다.)

Swagger 시작하기

-Swagger 사이트에 방문하여 회원 가입을 완료한 뒤 새로운 API를 생성하면 다음과 같은 팝업이 뜬다.

API 생성 팝업

이 때 Swagger에서 기본으로 Template을 여러개 지원하는데, PetStore는 Swagger에서 만든 튜토리얼(?) API 이다. 기본 구성에 익숙해지기 위해 한번정도 생성해본 뒤 살펴보는것도 좋을 것 같다.

---

petstore 생성 화면

petstore 템플릿을 생성하면 다음과 같이 나오게 된다. 왼쪽에 코드를 작성하는 부분은 yml형식이고, API의 설정값 등을 수동으로 넣어줄 수 있다. 오른쪽 위에 문서모양의 아이콘인 view Documentation을 누르면 다음과 같이 API 명세서만 깔끔하게 볼 수 있다.

---

API 명세서

다음과 같이 테스트도 진행할 수 있다.

테스트

---

스프링과 Swagger 연동

스프링에서는 간단한 Swagger 환경설정과 어노테이션을 통해 자동으로 API 명세서를 만들 수 있다.

이전에 만들어둔 itemservice 프로젝트에 swagger를 적용시켜 보겠다.

• 환경설정 추가(build.gradle)

// Swagger2 gradle
implementation (group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'){
    exclude module: 'swagger-annotations' exclude module: 'swagger-models'
}
implementation "io.swagger:swagger-annotations:1.5.21"
implementation "io.swagger:swagger-models:1.5.21"
implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'

2.9.2 버전을 전부 사용하면 오류가 발생해서 annotations와 models는 1.5.21 버전을 사용한다고 한다.

 

• SwaggerConfiguration

@Configuration
@EnableSwagger2
@EnableAutoConfiguration
public class SwaggerConfiguration {

    private final String version = "v1";

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Example API")
                .description("Swagger 소개를 위한 example")
                .build();
    }

    @Bean
    public Docket commonApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName(version)
                .apiInfo(this.apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.story.example"))
                .paths(PathSelectors.any())
                .build();
    }
}

config에 위와 같은 class를 추가하고 스프링 빈에 등록해준다.

또한 메인 클래스에도 @EnableSwagger2 어노테이션을 추가해줘야 한다!

 

• 오류 발생 시 해결방안

여기까지 진행하고 프로그램을 실행시키니

Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException: ~~~~

과 같은 에러가 발생했다. application.properties에 다음 코드를 넣어주니 해결 됐다.

#Swagger
spring.mvc.pathmatch.matching-strategy=ant-path-matcher

※application.yml 형식에서는 다음과 같은 코드를 넣어줘야 한다.

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

 

• 실행결과

정상적으로 실행이 되었다면 {호스트명}/swagger-ui.html# 에 접속하면 API 명세서가 자동으로 생성되어있다.

API 명세서 자동생성 결과

• 추가 설정

@ApiOperation 어노테이션을 통해 요청에 대한 간단한 정보,설명을 설정해줄 수 있다.

@ApiOperation(value = "아이템 정보", notes = "해당 아이템의 정보 출력")
    @GetMapping("/{itemId}")
    public String item(@PathVariable long itemId, Model model) {
        Item item = itemService.findById(itemId).get();
        model.addAttribute("item", item);
        return "item";
    }

 

APIOperation 설정 추가

이 외에도 @ApiResponses @ApiParam 등 다양한 어노테이션들이 있다. swagger를 사용하면서 익혀야할것 같다!

---

이상으로 Swagger의 초기 설정과 간편 설정에 대한 내용 포스팅을 마치겠다. 추후에 Swagger를 직접 이용해보고 협업 시 주의사항,유용한 설정등과 같은 꿀팁이 있으면 추가로 포스팅 하겠다!