Swagger-UI使用方法
Swagger-UI可以让任何人在不实现任何逻辑的情况下,以可视化的方式与后台服务端API接口方法进行交互。Swagger-UI的配置不会污染其他业务代码,我们通过引入Swagger-UI的配置即可自动生成相应的可视化接口文档,来对项目中的接口进行测试,这极大的简化了客户端与服务端的访问,方便开发和测试人员使用。
Swagger-UI官网以及其他开发者为其使用提供了多种配置方式,下面就以其中一种比较简单的配置方式进行讲解,具体步骤如下。
1.下载Swagger-UI项目
从GitHub上拉取Swagger-UI项目代码,具体的地址如下。
https://github.com/swagger-api/swagger-ui.git
2.引入Swagger-UI
找到本地下载好的Swagger-UI项目,进入项目并找到dist目录,将整个dist目录复制到需要使用Swagger-UI工具项目的resources目录下。这里以microservice-userservice项目为例,效果如图1所示。
图1 用户管理微服务加入Swagger-UI相关文件
从图1可以看出,加入的dist目录中的文件主要就是一些css、js和html等文件,都是用来显示和渲染Swagger-UI工具页面的。
3.加入Swagger依赖
在microservice-userservice项目的pom文件中加入Swagger的依赖,具体如下所示。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
4.编写配置类
在项目中创建一个Swagger-UI的配置类SwaggerConfiguration,并在该类中修改一些默认显示的API相关信息,其中最主要的是接口路径,编辑后如文件1所示。
文件1 SwaggerConfiguration.java
1 package com.itheima.config;
2 import org.slf4j.Logger;
3 import org.slf4j.LoggerFactory;
4 import org.springframework.context.annotation.Bean;
5 import org.springframework.context.annotation.Configuration;
6 import org.springframework.http.ResponseEntity;
7 import org.springframework.util.StopWatch;
8 import springfox.documentation.service.ApiInfo;
9 import springfox.documentation.spi.DocumentationType;
10 import springfox.documentation.spring.web.plugins.Docket;
11 import springfox.documentation.swagger2.annotations.EnableSwagger2;
12 import java.util.Date;
13 import static springfox.documentation.builders.PathSelectors.regex;
14 @Configuration
15 @EnableSwagger2
16 public class SwaggerConfiguration {
17 //定义API接口映射路径
18 public static final String DEFAULT_INCLUDE_PATTERN = "/user/.*";
19 private final Logger log =
20 LoggerFactory.getLogger(SwaggerConfiguration.class);
21 @Bean
22 public Docket swaggerSpringfoxDocket() {
23 log.debug("Starting Swagger");
24 StopWatch watch = new StopWatch();
25 watch.start();
26 //用于生成对应API接口文档的描述信息,可省略
27 ApiInfo apiInfo = new ApiInfo("用户管理API接口测试文档","description",
28 "termsOfServiceUrl","contact","version","","");
29 Docket docket = new Docket(DocumentationType.SWAGGER_2)
30 .apiInfo(apiInfo)
31 .genericModelSubstitutes(ResponseEntity.class)
32 .forCodeGeneration(true)
33 .genericModelSubstitutes(ResponseEntity.class)
34 .directModelSubstitute(java.time.LocalDate.class, String.class)
35 .directModelSubstitute(java.time.ZonedDateTime.class, Date.class)
36 .directModelSubstitute(java.time.LocalDateTime.class, Date.class)
37 .select()
38 .paths(regex(DEFAULT_INCLUDE_PATTERN))//匹配路径生成对应接口文档
39 .build();
40 watch.stop();
41 log.debug("Started Swagger in {} ms", watch.getTotalTimeMillis());
42 return docket;
43 }
44 }
上述配置类中,通过Docket对象配置了一些API接口文档生成信息,并通过build()方法生成对应的测试文档。其中配置的ApiInfo对象是用来在文档页面显示API接口描述信息的,可以省略;paths()方法用于匹配映射microservice-userservice项目中的以“/user/”开头的接口方法。
此处我们只是以microservice-userservice微服务为例展示了配置过程,而microservice-orderservice微服务项目配置Swagger-UI工具的方法与此相同,只需要更改SwaggerConfiguration类中的映射路径和ApiInfo信息即可。