转载

支付系统 - Swagger 的快乐你不懂[减压文]

前言

这篇文章聊一点放松的内容（反正我觉得挺放松挺解压的，水完这篇文章以后，我准备睡个好觉）

经常和前端联调的时候，需要提供文档（就很烦）。如果是自己新写的接口还好，怕就怕是之前的老接口，各种返回值的逻辑都不太清楚了，找原来的文档又找不到，找到了还一定是最新的。此时，我就在想能不能搞个东西让它自动生成文档。解决一下这个文档不跟着代码走的老大难问题。

好在是，优秀的人总是不谋而合，我随便搜了一下就找到了 Swagger 。虽然页面有点丑，但是无伤大雅。毕竟我是一个有内涵的人，外表什么的关了灯都一样（非开车）。所以这里我就从零记录了怎么在 SpringBooot 搭建的 Web 工程中使用这个工具。

因为是第一次摸索，难免有用的姿势不太正确的地方，肯定不是最佳实践。严格来讲不是一篇教程性质的文章，我称它为 减压文 ，如果有读者看见了觉得我误导了他，有本事你来打我啊。

正文

简介

既然是工具的使用，就做个简单的自我介绍。我， Swagger 是基于 Java 注解生成在线文档的一个框架，我的原理非常的简单。作为一个工具人，你们只要关注如何用好用出最高水平就行了。

Springboot 集成 Swagger

打开你的 POM ，引入下面的依赖。没有 POM ？请点击右上角的关闭按钮，相信你的心情也会好起来。

<dependency>
  <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>
复制代码

另外，需要自动激活配置，一般是在基于 annotation 的 Spring 配置类中加入 @EnableSwagger2 注解。没有基于注解的配置类？请点击右上角的关闭按钮，相信你的心情也会好起来。

@EnableSwagger2
@Configuration
public class PayOpenApiConfiguration{

    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("pleuvoir", "https://github.com/pleuvoir/compose-pay", "pleuvoir@foxmail.com");
        return new ApiInfoBuilder()
                .title("支付系统开放API")
                .description("支付系统开放API")
                .contact(contact)
                .version("1.0.0")
                .build();
    }
}
复制代码

还需要定义 Docket 对象，用来配置一些生效参数。其中 RequestHandlerSelectors.any() 配置的是 Swagger 包扫描的范围，你也可以配置为 RequestHandlerSelectors.basePackage("io.github.pleuvoir") 工程中指定的包。我最后配置的包，因为用 any 它给我搞了一些 Error 相关的东西出来，谁让你出来的，给我回去。

apiInfo 配置的内容包含标题，描述，版本，联系人等信息。相信聪明的你一看就知道，至于里面还有什么其他的配置点进去看看便知，我不想再这叨叨了。

有了这些配置框架层面的配置工作就完成了，接下里进入到万众期待的 api 声明环节。什么，你不期待？分手吧，我们不是一路人。请点击右上角的关闭按钮，相信你的心情也会好起来。

Swagger 接口配置示例

文章开头提到了，这是一项使用注解来生成文档的工具。那我们来看看都有哪些注解吧。为了方便围观，我将它们列在了表格中。

注解	作用域
@Api	类上
@ApiOperation	方法上
@ApiParam	方法的入参
@ApiImplicitParam	方法的入参
@ApiImplicitParams	方法的入参
@ApiModel	实体类
@ApiModelProperty	实体类中的属性
@ApiIgnore	类/方法/方法入参

说了你可能不信，就这么几个注解，还有这些作用域，我看着就感觉怪烦的，另外这些作用域还整理的时候还可能搞错了。到最后我也就只用到了 @ApiOperation @ApiModel @ApiModelProperty ，不信你自己往下看。

Swagger 接口配置示例

说一千道一万，不如看代码来的实在：

@ApiOperation(value = "发红包", notes = "创建红包活动", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
@RequestMapping(value = "createActivity", method = RequestMethod.POST)
public ResultMessageDTO<CreateActivityResultDTO> createActivity(@ApiParam @RequestBody CreateActivityDTO createActivityDTO) {
    ResultMessageDTO data = new ResultMessageDTO();
    data.setData(System.currentTimeMillis());
    return data;
}

@ApiModel("创建红包活动返回实体类")
public class CreateActivityDTO implements ToJSON {

  @ApiModelProperty("总金额")
  private BigDecimal totalAmount;

  @ApiModelProperty("用户编号")
  private Long userId;

  @ApiModelProperty("红包总数")
  private Integer total;

}

@ApiModel("创建红包活动返回结果实体类")
public class CreateActivityResultDTO {

  @ApiModelProperty("活动id")
  private Long activityId;
}
复制代码

别人的教程都说要在 Controller 的类上加 @Api 注解，我试了不加也没事，我就不加了。我是一个简单质朴的人，我喜欢简单，简单就是美，我希望我爱的人也是一个简单的人。

配置完成后根据你项目的请求地址访问自带的页面，我这里是 http://127.0.0.1:8081/swagger-ui.html ，可以看到一个 绿汪汪 的页面弹了出来。当然了，我这里只是示例，支付系统的相关接口还没有实现，所以就拿其它的 滥竽充数 。

对了，当我点击了发红包的按钮后发现了一件事情：

居然有个按钮让我 Try一Try ，这我不能忍啊，我就试着踹了一下，没想到索然无味之中发现了新的快乐。

这个东西有点意思，可以直接请求到后台，是不是以后可以偷懒不用 Postwomen 了，想到这里我有点小激动。

看到这个返回值我不禁感慨， 科技从业者的快乐就是这么简单 。好久没口吐芬芳了，虽然不知道骂了谁，但是好减压啊！今天我只想安安静静的做一个 祖安男孩 。

可能遇到的问题

与 guava 版本冲突

根据报错的提示，宁可能需要排掉一个版本，至于排哪个你自己去试。

找不到页面

访问 /swagger-ui.html 找不到页面，原因是 Swagger 的页面是打在 JAR 中的。

解决方法：如果是在 Springboot 中，在实现 WebMvcConfigurer 的配置类中增加如下代码：

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