[Docs] Swagger 도입

Swagger?

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

의존성 추가

dependencies {
    implementation 'io.springfox:springfox-boot-starter:3.0.0'
}

Swagger 3.x.x 버전 <-> spring boot 2.6.x 호환 이슈

application.yml 또는 application.properties 등에 다음과 같은 내용을 추가한다.
Spring boot 설정이 변경되면서 호환 이슈가 발생되었다고 한다.

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

Swagger 설정 클래스 생성

위치나 클래스명을 자유롭다.
본인의 경우, Config패키지 안에 SwaggerConfig.java를 생성하였다.

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;

@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any()) // 특정 패키지경로를 API문서화 한다. 1차 필터
                .paths(PathSelectors.any()) // apis중에서 특정 path조건 API만 문서화 하는 2차 필터
                .build()
                .groupName("API 1.0.0") // group별 명칭을 주어야 한다.
                .pathMapping("/")
                .apiInfo(apiInfo())
                .useDefaultResponseMessages(false); // 400,404,500 .. 표기를 ui에서 삭제한다.
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger 추가")
                .description("Swagger를 추가하였습니다.")
                .version("1.0.0")
                .termsOfServiceUrl("")
                .license("")
                .licenseUrl("")
                .build()
                ;
    }
}

Swagger-ui 실행

3.x.x : http://localhost:8080/swagger-ui/
config에서 설정했던 정보들이 표시됩니다.

Swagger Doc @Annotion 추가

• @Api
  • tags : 해당하는 XXXcontroller.java에 대한 제목 지정
• @ApiOperation
  • value : API에 대한 요약 작성
  • notes : API에 대한 자세한 설명 작성
• @ApiParam
  • value = : 파라미터에 대한 설명
  • example = : 파라미터의 default 값이 존재한다면 사용
  • required = true : 파라미터의 필수인지 표기 필수는 true, 아니면 false
  • 주의 : @ApiParam은 적용하는 파라미터의 컴마(,) 없이 사용해야 한다.

Reference

스웨거 (소프트웨어) - 위키백과, 우리 모두의 백과사전

 

Swagger API DOC 구축부터 실행까지