学科分类
目录
Docker

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信息即可。

点击此处
隐藏目录