使用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页面文档,在上面可以点击查看详情。
(tip:在application.properties中的静态资源路径配置可能导致你无法访问)

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

相关文章
相关标签/搜索