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

前言

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

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

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

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

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

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

正文

简介

既然是工具的使用,就做个简单的自我介绍。我, 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
,可以看到一个 绿汪汪
的页面弹了出来。当然了,我这里只是示例,支付系统的相关接口还没有实现,所以就拿其它的 滥竽充数

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

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

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

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

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

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

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

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

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

可能遇到的问题


guava
版本冲突

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

找不到页面

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

支付系统 - Swagger 的快乐你不懂[减压文]
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/");
  }
复制代码

然后再访问就可以了。如果没好,你自己再查查,我也不会。

资源集散地

百度一下,你就知道

后语

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

原文 

https://juejin.im/post/5f171a8f5188252e7705de38

本站部分文章源于互联网,本着传播知识、有益学习和研究的目的进行的转载,为网友免费提供。如有著作权人或出版方提出异议,本站将立即删除。如果您对文章转载有任何疑问请告之我们,以便我们及时纠正。

PS:推荐一个微信公众号: askHarries 或者qq群:474807195,里面会分享一些资深架构师录制的视频录像:有Spring,MyBatis,Netty源码分析,高并发、高性能、分布式、微服务架构的原理,JVM性能优化这些成为架构师必备的知识体系。还能领取免费的学习资源,目前受益良多

转载请注明原文出处:Harries Blog™ » 支付系统 – Swagger 的快乐你不懂[减压文]

赞 (0)
分享到:更多 ()

评论 0

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址