[Java] Swagger 설정

목표

Swagger를 통하여 다양한 API 호출을 진행해보는것이 이번 글의 목표입니다.

Swagger 란?

Swagger는 개발자가 Rest 웹 서비스를 설계, 빌드, 문서화 하는 일을 도와주는 프레임워크입니다.
혼자서 개발하는것이 아닌 협업을 하게 된다면 API를 제공하거나 기존 API를 분석해야되는데 이 때 Swagger를 통해서 API 정보를 확인할 수 있습니다.

Swagger 설정

• pom.xml

<!-- Swagger 설정 -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>3.0.0</version>
</dependency>

• SwaggerConfig.java
  java root 디렉토리에 conf 디렉토리를 생성 후 SwaggerConfig.java 파일을 생성합니다.

@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2) // 문서 형식 지정
                .apiInfo(this.apiInfo()) // API 정보 설정(title, description 등)
                .select()
                .apis(RequestHandlerSelectors.any()) // Swagger를 적용 할 package를 설정한다. 여기서는 모든 RequstMapping을 설정
                .paths(PathSelectors.any()) // 위의 API 중 특정 path에 대하여 설정한다. 여기서는 모든 path로 설정
                .build()
                .pathMapping("/");
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("First Project API") // Swagger UI에서 대표 Title을 설정합니다.
                .description("First Project API 정보 페이지") // Swagger UI에서 대표 설명을 설정합니다.
                .version("1.0") // Swagger UI에서 API의 버전 정보를 설정합니다.
                .build();
    }
}

• @Configuration : Java기반 환경 설정 시 Bean 생성을 하는 클래스를 뜻하게됩니다.
  해당 어노테이션을 붙이면 Spring 에서 자동으로 Scan을 해서 클래스 내부에 @Bean 어노테이션이 붙어있는 메소드로 빈을 생성합니다.

• @EnableSwagger2 : Swagger를 사용할 수 있게 해주는 어노테이션입니다. 이 어노테이션은 위에 있는 @Configuration 어노테이션과 함께 사용해야 합니다.

• @EnableWebMvc : Spring에서 지원하는 어노테이션으로 여러가지 MVC 설정들이 추가됩니다. 만약 이 어노테이션을 추가하지 않고 Swagger를 실행하면 아래 오류가 발생됩니다.

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

Controller에서 사용

위와 같이 설정이 끝났다면 이제는 Controller에서 어노테이션을 사용해서 Swagger를 적용해보겠습니다.

• FirstController

    @ApiResponses({
            @ApiResponse(code = 200, message = "ok"),
            @ApiResponse(code = 404, message = "page not found")
    })
    @ApiOperation(value = "회원 목록 조회", notes = "회원 목록 조회 API입니다.")
    @GetMapping("/0001")
    public ResponseEntity<List<MmbrVO>> getFirst(){
        List<MmbrVO> result = firstService.helloWorld();
        return new ResponseEntity<List<MmbrVO>>(result, HttpStatus.OK);
    }

기존에 작성했던 getFirst함수에 Swagger 관련 어노테이션을 추가하였습니다.

• @ApiResponse : code에 해당되는 응답에 대한 설명을 설정합니다.(실제 응답이 아닙니다.)
• ApiOperation : Swagger API정보를 나타냅니다.

실제 화면

사용까지 끝나고 나면 아래 URL을 통해 Swagger UI에 접속할 수 있습니다.

• http://localhost:8090/swagger-ui/index.html
  

전체 소스는 Gitlab 에서 확인할 수 있습니다.