快速编写你的 RESTFUL API 接口文档工具，通过注释定义接口和模型，可以和代码文件放置一起，也可以单独文件存放。
Swagger 优势
- 通过代码注解定义文档，更容易保持代码文档的一致性
- 模型复用，减少文档冗余，带来更可靠的文档
- 提供客户端访问接口，可以直接调试接口，不需要第三方工具进行调用测试接口
- 支持权限认证，等功能
下面详细介绍下Swagger的参数、对象和编写规范；一下是以Laravel 和Swagger为基础进行梳理分享，参考swagger官网文档进行整理，安装和简单使用 >>请这边走
一、 @OA\Info 声明一个API版本信息
Api版本信息、联系人/组织信息、许可信息
1、基础信息
参数
| 字段名称 | 类型 | 描述 |
|---|---|---|
| version | string | 需要 Api版本信息。 |
| title | string | 需要 API的标题。 |
| description | string | 参数的简要说明。 |
| termsOfService | string | API的服务条款。 |
| contact | 联系对象 | API的联系信息。 |
| license | 许可对象 | API的许可证信息。 |
2、@OA\Contact 联系信息
API的公开联系信息：参数如下
| 字段名称 | 类型 | 描述 |
|---|---|---|
| url | string | 联系人/组织的站点。 |
| name | string | 联系人/组织的名称。 |
| string | 联系人/组织的邮箱。 |
3、@OA\License 联系信息
API的公开许可信息：参数如下
| 字段名称 | 类型 | 描述 |
|---|---|---|
| url | string | 联系人/组织的站点。 |
| name | string | 联系人/组织的名称。 |
| string | 联系人/组织的邮箱。 |
二、@OA\Server 服务器新
API 服务器
| 字段名称 | 类型 | 描述 |
|---|---|---|
| url | string | Api服务器地址，。 |
| description | string | Api服务器描述。 |
| variables | string | 联系人/组织的邮箱。 |
三、@OA\Post、Get、Put、Delete 参数描述
| 字段名称 | 类型 | 描述 |
|---|---|---|
| tags | boolean | 接口名称。 |
| path | string | 需要。接口请求地址。 |
| summary | string | 接口简短描述，Ui界面在path后面展示，这个字段应该少于120个字符，对接友好 |
| description | string | 接口详情描述，接口展开描述接口功能或样例。 |
| operationId | string | 友好的操作描述名称，Id在api操作描述中名称唯一，工具库可以使用这个Id标识唯一的操作 |
| security | 安全对象 | 注明该请求使用哪些安全策略：值列表描述了可以使用的替代安全方案（也就是说，安全需求之间存在逻辑或）。该定义覆盖任何已声明的顶层security。要删除顶级安全声明，可以使用空数组。 |
| parameters | 参数对象 | 适用于此操作的参数列表。如果在路径项目中已经定义了一个参数，新的定义将覆盖它，但是不能删除它。该列表不得包含重复的参数。一个独特的参数是由一个名称和位置的组合来定义的。该列表可以使用引用对象链接到在Swagger对象参数中定义的参数(如果参数巨多可以使用ref引入params对象)。最多可以有一个“body”参数。 |
| responses | 响应对象 | 需要。执行此操作时返回的可能响应列表。 |
| schemes | string | 操作的传输协议。值必须是从列表：“http”，“https”，“ws”，“wss”。该值将覆盖Swagger对象schemes定义。 |
| deprecated | boolean | 声明此操作将被弃用。宣布的操作的使用应该被禁止。默认值是false。 |
| produces | string | 操作可以产生的类型列表。这将覆盖producesSwagger对象的定义。可以使用空值清除全局定义。值必须如MIME类型下所述 |
| consumes | string | 该操作可以使用的类型列表。这将覆盖consumesSwagger对象的定义。可以使用空值清除全局定义。值必须如MIME类型下所述。 |
| externalDocs | 外部文档对象 | 有关此操作的其他外部文档。 |
MIME类型必须类似如下（包含在 RFC 6838中)
application/json
application/xml
application/x-www-form-urlencoded
multipart/form-data
text/plain; charset=utf-8
text/html
application/pdf
image/png
示例
1、@OA\Parameter 参数说明
| 字段名称 | 类型 | 描述 |
|---|---|---|
| name | string | 需要。参数的名称。参数名称区分大小写。 |
| in | string | 需要。参数的位置。可能的值是“query”，“header”，“path”，“formData”或“body”。 |
| description | string | 参数的简要说明。这可能包含使用的例子。 |
| type | string | 参数的类型。取值权限：“string”，“number”，“integer”，“boolean”，“array”，“file”。 |
| required | boolean | 确定此参数是否是必需的。其默认值是false。 |
| format | string | 参数格式。 |
| default | * | 默认值。 |
示例：
2、@OA\Response 参数描述
| 字段名称 | 类型 | 描述 |
|---|---|---|
| description | string | 必填 响应的简短描述。。 |
| schema | 模式对象 | 响应结构的定义。它可以是一个基元，一个数组或一个对象。如果此字段不存在，则表示没有内容作为响应的一部分返回。 |
| headers | 标题对象 | 与响应一起发送的标题列表。 |
| examples | 示例对象 | 响应消息的一个例子。 |
示例：
3、@OA\Schema
4、@OA\SecurityScheme 鉴权
普通apiKey鉴权
示例演示渲染如下：
