Swagger UI

Swagger

1. 정의

• 개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크

2. 장점 & 사용이유

• 프로젝트 내에서 지정한 url들을 아래와 같이 자동으로 문서화해준다
• 간단히 api를 볼 수 있을 뿐만 아니라, 요청과 응답 테스트 또한 진행할 수 있다

3. 사용법

• 의존성 추가

• SwaggerConfig 추가

package org.zerock.b01.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
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;
//Springfox 프레임워크의 기본 인터페이스로 사용되는 빌더. 구성을 위한 합리적인 기본값과 편의 방법을 제공

@Configuration
public class SwaggerConfig {

    public Docket api() { //Swagger의 Docket 객체를 생성하는 메서드
        return new Docket(DocumentationType.OAS_30)  //Docket은 Swagger 설정의 핵심이며, 문서를 어떻게 구성할지를 정의
                .useDefaultResponseMessages(false)  //기본 응답 메시지를 사용하지 않도록 설정
                .select()  //API를 선택하는데 필요한 빌더를 시작
                .apis(RequestHandlerSelectors.basePackage("org.zerock.b01.controller"))  //특정 패키지 내의 컨트롤러 클래스에 있는 API들을 문서화 대상으로 선택합니다.
								.paths(PathSelectors.any()) //모든 경로를 문서화 대상으로 선택합
                .build() //Docket 객체를 빌드
                .apiInfo(apiInfo()); //API 문서에 대한 정보를 설정
								//apiInfo() 메서드에서 제공하는 내용을 기반으로 문서에 제목을 부여
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Boot 01 Project Swagger")
                .build();
    }
}

• CustomServletConfig 추가
  • 3버전은 SwaggerConfig를 추가 후 실행했을때 에러 발생 따라서 @EnableWebMvc 어노테이션을 추가한 것

@Configuration
@EnableWebMvc //웹 애플리케이션의 Spring MVC를 사용하여 커스터마이징하기 위한 어노테이션
public class CustomServletConfig {
}

• http://localhost:포트번호/swagger-ui/index.html 을 요청했을때 아래와 같이 출력
  

• 특정한 메소드를 선택하고 [Try it out] 버튼을 누르면 필요한 파라미터를 입력할 수 있는 화면이 나오고 화면 아래쪽에 필요한 값을 입력한 후에 [Execute]를 통해서 실행할 수 있다. 실행 후 결과를 바로 확인할 수 있다