接口文档使用说明

Swagger 介绍 Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。 Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测 Swagger支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口使用Swagger生成文档 流程

Swagger 是通过注解的方式来生成对应的 API，在接口上我们需要加上各种注解来描述这个接口，使用方法代码如下所示@Api 用在类上，说明该类的作用。可以标记一个 Controller 类作为 Swagger 文档资源，使用方式代码如下所示。

tags：接口说明，可以在页面中显示。可以配置多个，当配置多个的时候，在页面中会显示多个接口的信息 @ApiModel 用在类上，表示对类进行说明，用于实体类中的参数接收说明。使用方式代码如下所示

@ApiModelProperty() 用于字段，表示对 model 属性的说明。使用方式代码如下所示

@ApiParam 用于 Controller 中方法的参数说明。使用方式代码如下所示、

value：参数说明 required：是否必填 @ApiOperation 用在 Controller 里的方法上，说明方法的作用，每一个接口的定义。使用方式代码如下所示

value：接口名称 notes：详细说明 @ApiResponse 用于方法上，说明接口响应的一些信息；@ApiResponses 组装了多个 @ApiResponse。使用方式代码如下所示

@ApiImplicitParam 和 @ApiImplicitParams用于方法上，为单独的请求参数进行说明。使用方式代码如下所示

name：参数名，对应方法中单独的参数名称。 value：参数中文说明。 required：是否必填。 paramType：参数类型，取值为 path、query、body、header、form dataType：参数数据类型。 defaultValue：默认值。 开发人员按照以上加注解的方式能生成规范的接口文档，启动完成项目以后打开浏览器，访问：http://localhost:8080/swagger-ui.html，进入swagger接口文档界面,方便自测调试 http://localhost:8080/doc.html，进入swagger接口文档界面对外提供文档 特别注意事项 虽然说swagger是个好东西，但是使用中切不可以忽略的一个问题--【安全】。开放环境中你可以开放swagger给前端或者测试，千万不要把它开放给了生产，如果你的swagger ui不小心放到了生产，那是一件很可怕的事情切记切记