Spring Boot Swagger2自动生成接口文档

时间:2023-01-03 10:11:28

一、简介

  在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题:

  1、问题一、后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义?

  2、问题二、返回数据操作难:数据返回不对或者不够怎么办?怎么才能灵活的操作数据?

  这是很多公司前后端分离之后带来的困扰,那怎么来解决这些问题?

  问题一的一般解决方案:后端团队共同维护一个在线文档,每次改接口再去改对应的文档,但难免会遗漏,花的大力气但却效果平平。

  问题二的一般解决方案:自己搭建一个Mock服务器,然后一个接口一个接口手动去录规则,还是一个费力的体力活。

  那有没有最优的解决方案,来解决以上两个问题呢?答案是肯定的,那就是将要登场的“Swagger”和“Easy Mock”。

  1.1 Swagger介绍

    Swagger是全球最流行的接口文档自动生成和测试的框架,几乎支持所有的开发语言。

    Swagger官网地址:https://swagger.io/

二、Swagger集成

  2.1 添加依赖。

  配置pom.xml,添加如下代码:

Spring Boot Swagger2自动生成接口文档

  其中:

    springfox-swagger2 用于JSON API文档的生成;

springfox-swagger-ui 用于文档界面展示。

  2.2 注册Swagger

  在源码的根目录也就是Appliction.java的同级目录,创建Java类“SwaggerConfig.java”(命名无所谓),代码如下

  Spring Boot Swagger2自动生成接口文档

  其中“@ConditionalOnExpression”为Spring的注解,用户是否实例化本类,

  用于是否启用Swagger的判断(生产环境需要屏蔽Swagger)

  2.3 生产环境禁用Swagger

  是否启用Swagger是在application.properties文件里配置的,配置如下:

  swagger.enable=true

  生产环境禁用,设置为false即可。

  2.4 添加文档注释

  完成以上三个步骤,已经完成了Spring Boot对Swagger的集成,但是文档不够友好,比如类、接口的中文说明、参数的说明,是没有的,需要在代码中完成

  如下代码:

  Spring Boot Swagger2自动生成接口文档

  写完代码运行项目,在浏览器输入:http://localhost:8080/swagger-ui.html 查看添加注释的效果,如下图:

  Spring Boot Swagger2自动生成接口文档

  其中@Api是用来描述类的,@ApiOperation是用来描述方法的,@ApiImplicitParam是用来描述参数的,更多注解说明请看下文。

 三、Swagger文档注解

  常用注解介绍

  Spring Boot Swagger2自动生成接口文档

  我们现在已经对Swagger有了初步的认识,本节重点来看Swagger注解的使用。

  Swagger注解的作用是给接口添加注释的。

  3.1 @Api 类注释

    @Api:用来描述类的,属性如下

    1、tags 描述类的用途

    2、value 对显示而言没有任何用途可以不用设置

  代码示例:

  @Api(tags = "文章接口")

  3.2 @ApiOperation 方法注释

  @ApiOperation:用来描述方法的,属性如下:

  1、value 方法的描述

  2、notes 方法备注说明

  代码示例:

  @ApiOperation(value = "获取所有文章", notes = "查询分页数据")

  效果如下图:

  

  3.3 @ApiImplicitParams 参数注释

    @ApiImplicitParams:描述多参数

    @ApiImplicitParam:描述单参数

    

  代码示例:

  Spring Boot Swagger2自动生成接口文档

  效果如下图:

  Spring Boot Swagger2自动生成接口文档

  3.4 @ApiModel 实体对象描述

  @ApiModel:实体类名描述,属性如下:

    description 类描述

    @ApiModelProperty:字段描述,属性如下:

      value 字段描述

  示例如下

  Spring Boot Swagger2自动生成接口文档

  四、总结

  到此为止所有内容已经演示完了,我们解决前后端分离带来接口管理难、数据操作难的问题。自动生成接口文档、一键模拟数据,让我们不再依赖后端,只专注前端的业务,等后端把接口写完之后,再进行联合调试就可以了,这样我们就不费吹灰之力搞定了所有难题,并且灵活的配置让我们可以不影响和污染生产环境,生产环境设置禁用Swagger即可,并且有了预览功能之后我们甚至连Postman都省了。