Swagger 接口文档框架

前言

作为后端开放人员，最烦的事就是自己写接口文档和别人没有写接口文档，不管是前端还是后端开发，多多少少都会被接口文档所折磨，前端会抱怨后端没有及时更新接口文档，而后端又会觉得编写接口文档太过麻烦。Swagger 可以较好的接口接口文档的交互问题，以一套标准的规范定义接口以及相关的信息，就能做到生成各种格式的接口文档，生成多种语言和客户端和服务端的代码，以及在线接口调试页面等等。只需要更新 Swagger 描述文件，就能自动生成接口文档，做到前端、后端联调接口文档的及时性和便利性。

一、简介

官网：https://swagger.io/

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。
注：Spring boot项目需要导入依赖、配置SwaggerConfig.java文件，详见他人优秀文档：https://blog.csdn.net/lsqingfeng/article/details/123678701
若依架构配置好了可直接用。

Swagger 的优势

支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

二、注解

@ApiOperation 注解

@ApiOperation(“×××”) 常用于Controllerc接口、方法；表示一个http请求的操作。

@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”）；其他参数可参考源码；

• value：对该操作进行简单的描述，尽量控制在120字符以内。

• notes：对操作的详细描述。

• httpMethod：指定操作使用的HTTP方法类型，可选值“GET”、“HEAD”、“POST”、“PUT”、“DELETE”、“OPTIONS”和“PATCH”。

• tags：用来给操作打标签，Swagger UI 将在操作列表下面展示 tag 列表，每个 tag 下面展示拥有该 tag
  的操作列表。（就是分组）

@ApiOperation(value = "验证 @ApiOperation 注解",
        	  notes = "验证 @ApiOperation 注解 value 和 notes 属性的用法",
              httpMethod = "POST")
@RequestMapping("/demo1")
public void demo1() {
    //...
}

运行后的效果…

@ApiModel 注解

@ApiModel(value = “实体对象”, description = “”)，常标识实体类。

@ApiModelProperty 注解

@ApiModelProperty(“实体对象参数注释”)，常标识实体类参数。