SpringBoot 如何生成接口文档

为什么要用Swagger ?
作为一名程序员,我们最讨厌两件事:1. 别人不写注释。2. 自己写注释。

而作为一名接口开发者,我们同样讨厌两件事:1. 别人不写接口文档,文档不及时更新。2. 需要自己写接口文档,还需要及时更新。

相信无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。

而随着Springboot、Springcloud等微服务的流行,每个项目都有成百上千个接口调用,这时候再要求人工编写接口文档并且保证文档的实时更新几乎是一件不可能完成的事,所以这时候我们迫切需要一个工具,一个能帮我们自动化生成接口文档以及自动更新文档的工具。它就是Swagger。

Swagger 提供了一个全新的维护 API 文档的方式,有4大优点:

自动生成文档:只需要少量的注解,Swagger 就可以根据代码自动生成 API 文档,很好的保证了文档的时效性。
跨语言性,支持 40 多种语言。
Swagger UI 呈现出来的是一份可交互式的 API 文档,我们可以直接在文档页面尝试 API 的调用,省去了准备复杂的调用参数的过程。
还可以将文档规范导入相关的工具(例如 SoapUI), 这些工具将会为我们自动地创建自动化测试。
现在我们知道了Swagger的作用,接下来将其集成到我们项目中。

Swagger集成
集成Swagger很简单,只需要简单三步。

第一步: 引入依赖包

<!--swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!--swagger-ui-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

 

上一篇:Java 引入Swagger


下一篇:swagger