Gist & Cookbook ...

小目标:每天能够提交一行代码 ...

使用Swagger来构建我们的API文档

吴亮's Avatar 2019-12-11

  1. 1. Swagger在SpringBoot中的配置
    1. 1.1. 在pom.xml中增加依赖
    2. 1.2. 配置Configuration
    3. 1.3. 出现Whitelabel Error Page的解决办法

构建API文档的工具其实很多,比如我之前写C++时用得比较多的doxygen、还有我们团队用的比较频繁的APIDOC
但整体而言,我还是比较喜欢Swagger

Swagger在SpringBoot中的配置

总结一下Swagger在SpringBoot中的配置:

在pom.xml中增加依赖

1
2
3
4
5
6
7
8
9
10
11
12
13
<dependencies>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger2.version}</version>
</dependency>

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger2.version}</version>
</dependency>
</dependencies>

配置Configuration

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
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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 指定controller存放的目录路径
.apis(RequestHandlerSelectors.basePackage("com.github.wuliang142857.controllers"))
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("wuliang142857")
.termsOfServiceUrl("https://github.com/wuliang142857/")
.version("0.0.1")
.build();
}
}

一般而言,这样配置后就可以了,访问http://<host>:<port>/swagger-ui.html就可以看到相应的API文档了。

出现Whitelabel Error Page的解决办法

但有时候会出现Whitelabel Error Page,解决办法:自定义swagger-ui.html等资源的路径。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").addResourceLocations(
"classpath:/static/");
registry.addResourceHandler("swagger-ui.html").addResourceLocations(
"classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations(
"classpath:/META-INF/resources/webjars/");
}
}

本文作者 : 吴亮
本文使用 署名-非商业性使用-相同方式共享 4.0 国际 (CC BY-NC-SA 4.0) 协议
本文链接 : https://www.wuliang.me/2019/swagger-configuration/

本文最后更新于 天前,文中所描述的信息可能已发生改变