支付系统 - 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，不信你本身往下看。

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

@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，能够看到一个绿汪汪的页面弹了出来。固然了，我这里只是示例，支付系统的相关接口尚未实现，因此就拿其它的滥竽充数。

swagger-ui

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

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

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

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

可能遇到的问题

与 guava 版本冲突

根据报错的提示，宁肯能须要排掉一个版本，至于排哪一个你本身去试。

找不到页面

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

swagger-ui

解决方法：若是是在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/");  } 复制代码

而后再访问就能够了。若是没好，你本身再查查，我也不会。

资源集散地

百度一下，你就知道

后语

我没什么想说的，祝你们身体健康，万事如意，看完这篇文章后又年轻了五岁。没有人永远十八岁，但年年有人十八岁。晚安，美梦。