API Docs가 필요한 이유..
1. Swagger란?
백엔드 개발에 있어서 Web API를 문서화하기 위한 도구이며, 쉽게는 제품의 설명서라고도 생각할 수 있다.
간단한 설정으로 프로젝트의 API 목록을 웹에서 확인 및 테스트 가능하게 하는 라이브러리이고
특히 RESTful API를 문서화시키고 관리하는 것에 많이 쓰인다.
API 문서를 일반 문서로 작성하게 되면 API가 변경될 때마다 문서를 함께 수정해줘야 하는 번거로움이 있는데 SpringBoot에서는 Swagger를 사용하면 문서 수정을 자동화할 수 있다.
RESTful API 를 테스트할 수 있다는 것도 큰 장점이다.
참고로 Swagger는 Java에 종속된 라이브러리는 아니고, Node.js( swagger-ui-express , swagger-jsdoc ), Laravel ( L5 Swagger ) 등 언어마다 다양한 에코시스템 프로젝트가 있다.
2. build.gradle 의존성 추가
사용할 gradle dependency는 링크에서 찾을 수 있다.
dependencies {
implementation 'io.springfox:springfox-boot-starter:3.0.0'
}
ℹ️ Swagger 3.x.x 이후 부터 접속url 변경 등 2.x.x 와 3.x.x 는 차이점이 있다. 해당 프로젝트는 Swagger 3.0.0을 사용한다.
ℹ️ Swagger 3.x.x 버전 호환 이슈 해결
에러 메세지: failed to start bean 'documentationpluginsbootstrapper'; nested exception is java.lang.nullpointerexception
spring boot 2.6.x 버전과 Swagger 3.x.x 간에 호환 이슈가 있기에 아래처럼 Porject별 설정 파일 (application.yml 혹은 application.properties)에 추가해야 한다. Spring Boot에서 설정이 변경되어 호환 이슈가 발생한다고 한다. 해결 방법으로는 application.yml 파일 혹은 application.properties 파일에 다음 설정을 추가하면 된다.
1) application.yml
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher
2) application.properties
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
3) 나의 경우 위 설정방법을 추가해도 장애가 발생했는데, Spring Boot 버전을 2.6.X -> 2.5.X로 낮춰서 해결했다.
3. Swagger 설정
swagger 설정을 위해 SwaggerConfig 클래스를 생성한다. 클래스 이름은 임의로 작성해도 된다.
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
@Configuration
@EnableSwagger2
@EnableAutoConfiguration
public class SwaggerConfiguration {
private String version;
private String title;
@Bean
public Docket api() {
version = "v1";
title = "aLittleVanilla API " + version;
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.minji.vbackend"))
.paths(PathSelectors.any())
.build()
.groupName(version)
.useDefaultResponseMessages(false)
.apiInfo(apiInfo(title, version))
.useDefaultResponseMessages(false);
}
private ApiInfo apiInfo(String title, String version) {
return new ApiInfo(
title,
"A Little Vanilla API Docs",
version,
"http://www.alittlevanilla.kro.kr/",
new Contact("Contact Me", "https://blog.naver.com/ghdalswl77", "ghdalswl77@naver.com"),
"Licenses",
"http://www.alittlevanilla.kro.kr/",
new ArrayList<>());
}
}
@EnableSwagger2
Swagger2 버전을 활성화 하겠다는 어노테이션.
Docket
Swagger 설정의 핵심이 되는 Bean. API 자체에 대한 스펙은 컨트롤러에서 작성함.
useDefaultResponseMessages()
false로 설정하면, swagger에서 제공해주는 응답코드 ( 200,401,403,404 )에 대한 기본 메시지를 제거한다.
불필요한 응답코드와 메시지를 제거하기 위함이며, 컨트롤러에서 명시해줄 것이다.
groupName()
- Docket Bean이 한 개일 경우 : 기본 값은 default이므로, 생략가능
- 여러 Docket Bean을 생성했을 경우 : groupName이 충돌하지 않아야 하므로, 여기서는 각 Docket Bean의 버전을 명시해주었다.
select()
ApiSelectorBuilder를 생성
apis()
api 스펙이 작성되어 있는 패키지를 지정한다. 즉, 컨트롤러가 존재하는 패키지를 basepackage로 지정하여, RequestMapping( GetMapping, PostMapping ... )이 선언된 API를 문서화한다.
paths()
apis()로 선택되어진 API중 특정 path 조건에 맞는 API들을 다시 필터링하여 문서화합니다.
apiInfo()
제목, 설명 등 문서에 대한 정보들을 보여주기 위해 호출한다.
파라미터 정보: public ApiInfo( title, description, version, termsOfServiceUrl, contact, license, licenseUrl, vendorExtensions )
2.5 버전 추가
@Bean
public Docket api() {
version = "v2";
title = "aLittleVanilla API " + version;
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("com.minji.vbackend"))
.paths(PathSelectors.any())
.build()
.groupName(version)
.useDefaultResponseMessages(false)
.apiInfo(apiInfo(title, version))
.useDefaultResponseMessages(false);
}
위 클래스에 이렇게 추가하면 된다.
3. Controller (API)에 Swagger DOC 어노테이션 추가
@Api
- value : 태그
- tags : 해당하는 XXXXcontroller.java 에 대한 Title명칭 부여
@ApiOperation : 한개의 API URL과 메서드 선언
- value : API에 대한 간략한 설명 요약하여 작성 (title 같이)
- notes : API에 대한 자세한 설명 작성
@ApiParam
- value= 파라미터에 대한 설명 description
- example = 파라미터의 default 값이 있을 때 사용
- required = true : 파라미터의 필수인지 표기 필수는 true, 아니면 false
- %주의%, @ApiParam은 적용하는 파라미터의 컴마 없이 사용해야 한다.
3. 화면 예시
프로젝트 실행 후 http://localhost:8080/swagger-ui/#/ 로 접속.
4. response를 글로벌 메시지로 설정
응답코드와 헤더 그리고 응답에 대한 설명을 명시할 수 있다.
swaggerconfig.java 파일에 다음을 추가한다.
@Bean
public Docket api() {
version = "v1";
title = "aLittleVanilla API " + version;
List<ResponseMessage> responseMessages = new ArrayList<>();
responseMessages.add(new ResponseMessageBuilder()
.code(200)
.message("OK!")
.build());
responseMessages.add(new ResponseMessageBuilder()
.code(404)
.message("Not Found.")
.build());
responseMessages.add(new ResponseMessageBuilder()
.code(500)
.message("Internal Server Error.")
.build());