[Spring] API 문서 자동화 1 - Swagger

✨ api 문서화 정리 글

1. Swagger
2. Spring Rest Docs
3. RestDocs + Swagger-UI 같이사용하기

 

이번에는 API 문서 자동화를 해보려 한다.

 

API 문서 자동화 방법은 지금까지 내가 알기로는

1. 스웨거 (Swagger)

2. Spring RestDoc

 

2가지 방법이 존재하고, 2번은,  Spring에서만 되는거 같기 때문에, Swagger를 사용해보고, Spring RestDoc을 마지막으로 적용해볼 예정이다.

---

 

1. 스웨거란 (Swagger)

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

 

Swagger란, 간단한 설정으로 프로젝트에서 지정한 URL들을 HTML화면으로 확인할 수 있게 해주는 프로젝트라고 한다.

한번 해보자~

 

2. 스웨거 사용 방법

1) Swagger 의존성 추가

https://mvnrepository.com/artifact/io.springfox/springfox-swagger2/2.9.2

build.gradle

dependencies {
    //Swagger
    implementation 'io.springfox:springfox-swagger2:2.9.2'
    implementation 'io.springfox:springfox-swagger-ui:2.9.2'
}

 

2) Swagger 설정 추가

@EnableSwagger2 어노테이션을 추가하여 기능을 활성해준다.

NOTE

@EnableSwagger2 어노테이션은 main 쪽에 추가해도 되지만, 아래에서 생성할 Swagger2Config.java 에 추가해도 된다고한다.

 

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any()) // 현재 RequestMapping으로 할당된 모든 URL 리스트를 추출
                .paths(PathSelectors.ant("/api/**")) // 그중 /api/** 인 URL들만 필터링
                .build();
    }
}

 

3) Swagger 결과확인

 

• Swgger URL: http://<ip>:<port>/<base>/swagger-ui.html
• 예: http://localhost:8080/swagger-ui.html

위와 같은 URL 들어가면 확인이 가능하다

 

조금더 스웨거 커스터마이징을 해보자

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any()) // 현재 RequestMapping으로 할당된 모든 URL 리스트를 추출
                .paths(PathSelectors.ant("/**")) // 그중 /api/** 인 URL들만 필터링
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Team MaruMaru Spring Boot REST API")
                .version("1.0.0")
                .description("반려동물 커뮤니티 marumaru 프로젝트의 swagger api 입니다.")
                .build();
    }
}

조오금 더 이뻐짐

*참고

https://memostack.tistory.com/17