0%

spring boot Swagger 와 REST API 문서 자동화

Posted on Edited on

swagger 를 이용하여 Spring 의 REST API 문서를 자동화하는 방법을 정리합니다.

API를 제공하려면 가이드 문서 제공은 필수적입니다.
그런데 개발을 진행하면서 기능이 추가될때마다 별도로 문서를 작성하고 갱신하는것에는 많은 비용이 따릅니다.
따라서 swagger 를 활용해 이런 문제를 해소할 수 있습니다.

의존성 등록

1
2
3
4
5
6
7
8
dependencies {
    ..
    ..
    compile 'io.springfox:springfox-swagger2:2.4.0'
    compile 'io.springfox:springfox-swagger-ui:2.4.0'
    ..
    ..
}

Config 설정

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
package com.devwook88.learn_spring_boot.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger.web.UiConfiguration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import static springfox.documentation.builders.PathSelectors.regex;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    private ApiInfo metadata() {
        return new ApiInfoBuilder()
                .title("JPub Spring Boot")
                .description("Spring Boot Rest API")
                .version("1.0")
                .build();
    }

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any()) // 모든 경로를 문서화
                // .paths(regex("/basic/.*")) // /basic/ 하위 경로를 문서화
                .build()
                .apiInfo(metadata());
    }
}

설정이므로 최상단에 @Configuration 과 swagger 를 이용하기위해 @EnableSwagger2 어노테이션을 추가합니다.

ApiInfo 에는 API 의 기본정보를 저장할 수 있습니다.

문서화는 전체를 지정하거나 특정 URI 를 지정할 수 있습니다

1
2
3
paths(PathSelectors.any())
or
paths(regex("/basic/.*"))

swagger 는 문서가 참조할 API 경로와 메타 정보를 포함해서 Docket 인스턴스를 생성하고
이를 기준으로 동작합니다.

docs

서버를 구동하고 아래 URL을 통해 결과를 확인할 수 있습니다.
http://localhost:8080/swagger-ui.html

github

swagger 에 대한 자세한 정보는 아래 github 에서 구체적으로 확인할 수 있습니다.
https://github.com/swagger-api/swagger-core/wiki/Annotations