Swagger 이용하기

 Swagger란?

• REST API 를 설계, 빌드, 문서화 및 사용하는데 도움이 되는 OpenAPI 사양을 중심으로 구축된 오픈 소스 도구 세트
• 코드 몇 줄 추가를 통해 적용하기 쉬우며, 문서 화면에서 UI를 통해 바로 API 테스트가 가능한 장점

 

Gradle을 사용하고 있다면 다음과 같은 dependencies를 추가해주자.

implementation 'io.springfox:springfox-boot-starter:3.0.0'

https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui/3.0.0

여기서 원하는 depency들을 gradle또는 maven으로 찾을 수 있다.

(2버전이나 3버전이나 큰 차이는 없다고 한다.)

 

• Swagger 2.x 버전보다 간단하게 springfox-boot-starter 하나 추가로 필요한 모든 라이브러리 포함 가능

 

• Spring Boot 로컬 실행 후 URL 접속
• 아래와 같이 접속
  • Swagger2 : http://localhost:8080/swagger-ui.html
  • Swagger3 : http://localhost:8080/swagger-ui/index.html

 

 

 

@Configuration
@EnableSwagger2
public class SwaggerConfig {  // Swagger

    private static final String API_NAME = "Login API";
    private static final String API_VERSION = "0.0.1";
    private static final String API_DESCRIPTION = "Login API 명세서";

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("hello.login.web"))  // Swagger를 적용할 클래스의 package명
                .paths(PathSelectors.any())  // 해당 package 하위에 있는 모든 url에 적용
                .build()
                .apiInfo(apiInfo());
    }

    public ApiInfo apiInfo() {  // API의 이름, 현재 버전, API에 대한 정보
        return new ApiInfoBuilder()
                .title(API_NAME)
                .version(API_VERSION)
                .description(API_DESCRIPTION)
                .build();
    }
}

Swagger를 사용하기 위한 설정이다.

 

 

 

 

 

작성했던 컨트롤러 별로 구성했던 API의 목록들을 확인할 수 있다.

 

 

tryout을 눌러 값을 입력하여 나오는 값들을 확인해 볼 수 있다.

지금 만들어 놓은 controller들은 view를 반환하기 때문에

로그인 여부에 따라 달라지는 view의 코드들이 모두보여지게 된다.

 

만일 responseBody로 API를 제공하는 목적으로 JSON을 return한다고 하면

postMan처럼 해당 JSON이 보여질 것이다.

 

@Operation(summary = "요약정보", description = "로그인POST")
@ApiResponse(message = "good", code = 200)
@PostMapping("/login")
public String loginV4(@Valid @ModelAttribute LoginForm form, BindingResult bindingResult,
                      @RequestParam(defaultValue = "/") String redirectURL,
                      HttpServletRequest request) {

해당 어노테이션으로 각 API의 응답형태와 설명들을 추가할 수 있다.