使用Swagger2自动生成RestApi页面文档

Swagger2自动生成RestApi文档

前言

目前RestApi很流行，归根结底有两个主要原因：

1、在多终端普及的情况下，RESTful风格Api的使用越来越频繁；
2、随着公司规模的扩大，前后端工程师的数量增加，如何才能在一个项目中更好地沟通？接口的定义和接口文档的规范成了关键点，RESTful在其中扮演者重要角色。

REST定义着接口的规范，Swagger2生成接口文档；
有了Swagger2，不用再去写复杂的接口文档，也不用担心接口的更新会导致文档的报废；
那么如何掌握Swagger2呢？这就是该文章存在的意义。

本篇主要讲解的就是如何在Spring Boot上使用Swagger2

第一步：添加maven依赖

需要添加两个依赖，注意版本相同：

第二步：编写Swagger2配置类

通过createRestApi()方法返回Docket，调用以下方法：
apiInfo()方法中可以添加api文档的基本信息（具体类型查看文档）；
select()方法返回ApiSelectorBuilder实例，用于过滤哪些api需要显示；
apis()方法中填写项目中Controller类存放的路径；
最后build()建立Docket。

第三步：添加文档中的api和参数

如何在api文档中选择要显示的api和对应参数，
我们需要在具体api上加上注解：

以上面的login方法为例：
@ApiOperation用来描述api；
@ApiImplicitParams定义多个参数（如果只有一个参数可以不用）；
@ApiImplicitParam用来描述传入参数。

到这里配置和注入已经完成，
接下来我们进入http://localhost:8088/swagger-ui.html查看api文档：

如图所示，就是RESTful的api页面文档，在上面可以点击查看详情。

注意点

在application.properties中的静态资源路径配置可能导致你无法访问；
但是有同学就问了：不配置静态资源路径怎么拿到静态资源？
我们看下swagger的包的所在路径：

所以在配置好的spring静态资源访问路径后加上,classpath:/META-INF/resources

如此这般，就能在前后端分离的情况下使用swagger2了

以上便是Swagger2在Spring Boot上的应用；
觉得还可以的请点个赞，赞不了也可以收藏下；
总之，谢谢阅读～