Spring swagger 3.0.0 설정

<피드백 언제나 환영합니다! 댓글 감사합니다>

swagger는 RestFul APi → OpenAPI 스펙을 기준으로 문서화 해서 HTML 페이지로 바꿔주는 역활을 합니다.

저는 3.0.0 을 기준으로 작성하였으며 2.X.X 의 경우 조금 다릅니다. 아래 springfox 문서를 통해서 작성했으며 간단하게 알아보도록 하겠습니다.

Springfox Reference Documentation

https://springfox.github.io/springfox/docs/current/

Spring 설정

• spring 2.7.0

• java 17

• dependency : Spring Web, Lombok

dependency 는 하나씩 추가하면서 해보도록 하겠습니다.

라이브러리 추가

....
dependencies {
    ....
	  // https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui
    implementation 'io.springfox:springfox-swagger-ui:3.0.0'
    // https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter
    implementation 'io.springfox:springfox-boot-starter:3.0.0'
}
....

3.0.0 버전을 사용했으며 UI 및 기타 설정시 2.X.X 버전과 다를수 있습니다.

* Swagger 버전에 따른 UI URL 체크* 
2.X.X  :  http://localhost:8080/swagger-ui.html
3.X.X  :  http://localhost:8080/swagger-ui/index.html

간단한 코드 작성

• SwaggerConfig.java

  package com.example.swagger_restdocs.swagger;
  
  import org.springframework.context.annotation.Bean;
  import org.springframework.context.annotation.Configuration;
  import springfox.documentation.builders.ApiInfoBuilder;
  import springfox.documentation.builders.PathSelectors;
  import springfox.documentation.builders.RequestHandlerSelectors;
  import springfox.documentation.service.ApiInfo;
  import springfox.documentation.spi.DocumentationType;
  import springfox.documentation.spring.web.plugins.Docket;
  import springfox.documentation.swagger2.annotations.EnableSwagger2;
  
  @Configuration
  @EnableSwagger2
  public class SwaggerConfig {
      private final static String API_NAME = "Swagger_Study API";
      private final static String API_VERSION = "0.0.1";
      private final static String API_DESCRIPTION = "Swagger_Study API 명세서";
  
      @Bean
      public Docket api(){
          return new Docket(DocumentationType.SWAGGER_2)
                  .select()
                  .apis(RequestHandlerSelectors.any())
                  .paths(PathSelectors.any())
                  .build().apiInfo(apiInfo());
      }
  
      private ApiInfo apiInfo() {
          return new ApiInfoBuilder()
                  .title(API_NAME)
                  .description(API_DESCRIPTION)
                  .version(API_VERSION)
                  .build();
      }
  }

• @EnableSwagger2 → Swagger2 활성화

• new Docket(DocumentationType.SWAGGER_2).select() → API 에 사용되는 builder 생성 입니다.

• apis() → RequestHandlerSelectors 를 이용 api 스펙이 작성되는 즉, Controller 부 basepackage를 지정 합니다.

• paths() → PathSelectors를 이용 apis() 에 선택된 스팩들중 특정 path 조건을 다시 필터링 합니다.

• ApiInfo → Swagger에 사용되는 title, description, version 등이 사용이됩니다.

위 관련 설정은 가장 기본적인 설정이며 지금은 저런 설정이 있다 정도만 알아둘 예정입니다. (나중에 조금더 심층적으로 파보겠습니다.)

⨳위 설정후 Swagger UI를 통해 기본적인 UI를 확인할수 있습니다. 하지만 3.0.0 부터는 빌드시 Err 가 발생합니다.

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; 
nested exception is java.lang.NullPointerException: Cannot invoke 
"org.springframework.web.servlet.mvc.condition.PatternsRequestCondition.getPatterns()" because "this.condition" is null
// 위 같이 Err 발생시 application.yml 파일에 설정을 해야할게 하나 있습니다.

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

• TestController.java

  package com.example.swagger_restdocs.controller;
  
  import io.swagger.annotations.*;
  import org.springframework.web.bind.annotation.GetMapping;
  import org.springframework.web.bind.annotation.RequestParam;
  import org.springframework.web.bind.annotation.RestController;
  
  import java.time.LocalDateTime;
  import java.util.HashMap;
  import java.util.Map;
  
  @RestController
  public class TestController {
  
      @ApiOperation(value = "user", notes = "user 정보")
      @GetMapping(value = "/user")
      public UserDto helloUser(){
          UserDto userDto = new UserDto();
          userDto.setId(5);
          userDto.setName("hello");
          userDto.setStatus(true);
          userDto.setCreateAt(LocalDateTime.now());
          return userDto;
      }
  
      @ApiOperation(value = "paramSample", notes = "테스트입니다")
      @ApiResponses({
              @ApiResponse(code = 200, message = "ok"),
              @ApiResponse(code = 404, message = "페이지 못찾음")
      })
      @GetMapping(value = "/paramSample")
      public Map<String, String> selectBoard(@ApiParam(value = "샘플번호", required = true, example = "1")
                                             @RequestParam String no) {
  
          Map<String, String> result = new HashMap<>();
          result.put(no, "테스트");
          result.put("test contents", "테스트 내용");
          return  result;
      }
  }

• UserDto.java

  package com.example.swagger_restdocs.controller;
  
  import io.swagger.annotations.ApiModelProperty;
  import lombok.Data;
  import java.time.LocalDateTime;
  
  @Data
  public class UserDto {
      @ApiModelProperty(example = "유저 아이디")
      private Integer id;
      @ApiModelProperty(example = "유저 이름")
      private String name;
      private boolean status;
      private LocalDateTime createAt;
  }
  

• @ApiOperation → 어노테이션을 API에 추가해 API에 대한 주석을 달 수 있음(옵션)

• @ApiResponses → response 상태 값에 따라 설명을 적어놓는 있다

• @ApiParam → @RequestParam 시 필요한 부분을 테스트 할수 있도록 적어 놓은 부분

• @ApiModelProperty → Dto 들의 값(JSON) 표현시 사용되는 일종의 값

Swagger UI

위 그림처럼 표현 되며 페이지에 Rest Api 가 문서화 되서 생성이 된다. 주요 할점은 2.X.X 랑 3.0.0의 URL 주소 방식이 다르기 때문에 꼭 비교하면서 써야한다.

github 코드 : https://github.com/Eco-Min/Swagger

Uploaded by Notion2Tistory v1.1.0