Swagger 적용하기 - REST API 명세를 문서화 하는 방법

Swagger

 - 서버로 요청되는 API 리스트를 HTML 화면으로 문서화

 - 서버가 가동되면서 @RestController 를 읽어 API를 분석하여 HTML 문서를 작성한다.

 

협업을 위해 필요한 라이브러리

API 를 개발하면 명세를 관리해야 한다.

 

명세 란 ,  아래의 내용을 정리한 자료이다.

 1. 해당 API가 어떤 로직을 수행하는지 설명

 2. 이 로직을 수행하기 위해 어떤 값을 요청하는지

 3. 이에 따른 응답값으로는 무엇을 받을 수 있는지 

---

먼저 의존성을 주입해준다.

implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'

---

Swagger 설정 코드를 작성한다.

설정(Configuration) 에 관련된 코드이므로, 패키지와 클래스를 따로 생성한 후 작성했다.

 

@Configuration : 어노테이션 기반의 환경 구성을 돕는다. Ioc 컨테이너에게 해당 클래스를 Bean 구성 Class 임을 알림

@Bean : 개발자가 직접 제어가 불가능한 외부 라이브러리 등을 Bean으로 만들 경우에 사용

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                
               // 해당 부분만 경로확인
                .apis(RequestHandlerSelectors.basePackage("com.springboot.api"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot Open API TEST with Swagger")
                .description("설명 부분입니다.")
                .version("1.0.0")
                .build();
    }
}

---

++ 추가

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

 

해당오류가 발생하면 application.properties 에 아래 코드를 추가해준다.

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

---

 

코드에 관한 설명은 작성 후 Swagger 페이지를 열어 확인하는 것이 더 빠른 이해가 될 것 같다.

사용방법은 타 블로그를 봐도 크게 다르지 않다.

적용 후 프로그램 재시작 -> http://localhost:8080/swagger-ui.html 해당 링크로 들어간다.

 

apiInfo 메서드 부분은 아래와 같이 표시된다.

---

지금까지 작성한 API 컨트롤러에 관한 내용을 볼 수 있다.

---

추가적으로 API 명세 관리 뿐만 아니라 직접 통신을 진행할 수 있다.

먼저, get-controller 에서 명세의 세부 내용을 설정했다.

@ApiOperation(value = "GET 메서드 예제", notes = "@ReqeustParam을 활용한 GET Method")
@GetMapping("/reqeust1")
public String getRequestParam1(
        @ApiParam(value = "이름", required = true) @RequestParam String name,
        @ApiParam(value = "이메일", required = true) @RequestParam String email,
        @ApiParam(value = "회사", required = true) @RequestParam String organization) {
    return name + " " + email + " " + organization;
}

해당 내용 또한 직접 들어가서 확인할 수 있다.

아래와 같이 세부 상세내용이 적용된것을 확인할 수 있다.

직접 통신을 시도해보면 아래와 같이 나타난다.

 

 

 

참고 

 - 스프링부트 핵심 가이드

 - https://www.youtube.com/watch?v=Q27PGBYmHNA&list=PLlTylS8uB2fBOi6uzvMpojFrNe7sRmlzU&index=11