0到1实现thinkphp6+swagger-php3.0配置管理接口文档
Swagger 是什么？
Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。
Composer安装安装swagger-php3.0
安装swagger-php后端，在thinkphp6框架的总目录下面执行，composer安装swagger-php插件。（注意：本小册针对swagger-php3.0）
composer require zircote/swagger-php:3.0.*Swagger-ui配置
官网地址：REST API Documentation Tool | Swagger UI
前端部分下载一份swagger-ui到根目录public中。
//找到swagger-ui的index.html页面
window.onload = function() {
// Begin Swagger UI call region
const ui = SwaggerUIBundle({
//url:"站点访问地址/swagger.json", //单文档地址
urls:[
{url:"站点访问地址/swagger.json",name:"前端文档"},
{url:"站点访问地址/swagger-1.json",name:"后端文档"}
], //开启Topbar插件支持多个文档
dom_id: '#swagger-ui',
deepLinking: false,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})通过控制器代码自动生成swagger.json
在控制器index中填入以下内容生成swagger.json
toJson());
if ($res == true) {
return redirect('站点访问地址/swagger-ui/dist/index.html');
}
}
}显示如下图代表配置正常：
Swagger配置说明
全局安全配置
OpenAPI支持的方案包括基本身份验证、API密钥（作为头或作为查询参数）和OAuth2的公共流（隐式、密码、应用程序和访问代码）。在Swagger中使用@OA\SecurityScheme定义全局安全配置。
参数说明：
| 参数 | 含义 |
| securityDefinition | swager->securityDefinitions数组中的键 |
| type | 类型 值为 http、openIdConnect、apiKey、oauth2 |
| name | 名称 |
| in | 需要API密钥的位置 值为 query、header、cookie |
| scheme | 安全参数内容为以 bearer开头 |
| bearerFormat | 文档目的，可选的任意值 |
用法如下：
/**
*@OA\SecurityScheme(type="http",securityScheme="Authorization",name="Authorization",in="header",scheme="Bearer",bearerFormat="JWT")
*/
POST请求
可以通过@OA\Post() 设置post请求类型的注释
/* @OA\Post(
* path="/index/register/index",
* tags={"用户相关"},
* summary="用户注册",
* security={{"Authorization"={}}},
* description="用户注册逻辑说明",
* /)参数说明：
| 参数 | 含义 |
| path | 请求路径 |
| tags | 用于API文档控制的标记列表。标记可用于按资源或任何其他限定符对操作进行逻辑分组 |
| summary | 接口名称 |
| security | 接口的安全设置，填入安全设置的securityScheme命名 |
注意：@OA\Get(),@OA\Post(),@OA\Delete(),@OA\Put()，4种请求方式里面的参数都相同所以只写了POST的请求示例
Parameter参数设置
参数@OA\Parameter()是配合@OA\Post(),@OA\Get(),@OA\Delete(),@OA\Put()使用设置请求参数的。
/** @OA\Post(
* path="/index/register/index",
* tags={"用户相关"},
* summary="用户注册",
* @OA\Parameter(
* in="query",
* required=false,
* name="simg",
* @OA\Schema(type="integer"),
* description="description",
* )
* )
*/参数说明：
| 参数 | 含义 |
| ref | 允许此路径项的外部定义 |
| in | 参数的位置，可设置的值为“query”、“header”、“path” |
| description | 描述 |
| required | 确定此参数是否是必需的值可设置的值为 true 或 false |
| type | 参数的类型,可设置值是“string”、“number”、“integer”、“boolean”、“array” |
| format | 类型的扩展格式 |
| items | 描述Array上的项目类型 |
| collectionFormat | 数组的格式 |
| default | 设置参数的默认值。值的类型取决于定义的类型 |
Response参数设置
使用@OA\Response()定义response
/** @OA\Response(
* response="200",
* description="状态码、提示消息",
* @OA\MediaType(mediaType="application/json",
* @OA\Schema(
* required={"code","message"},
* @OA\Property(
* property="code",
* type="integer",
* format="int32",
* description="状态码"
* ),
* @OA\Property(
* property="message",
* type="string",
* description="提示消息"
* )
* )
* )
*)
*/参数说明：
| 参数 | 含义 |
| ref | 允许此路径项的外部定义 |
| response | 状态 |
| description | 描述 |
| Schema | 描述响应正文 |
| MediaType | 响应类型 |
| example | 描述例子 |
将上述参数整理成一个完整的post请求返回
/**
* @OA\SecurityScheme(type="http",securityScheme="Authorization-Bearer",name="Authorization",in="header",scheme="Bearer",bearerFormat="JWT")
* @OA\Post(
* tags={"用户相关"},
* summary="注册接口",
* @OA\Parameter(name="firstname",in="query",@OA\Schema(type="integer"),description="firstname"),
* security={{"Authorization-Bearer"={}}},
* path="/index/register/index",
* @OA\RequestBody(required=true,description="body",content={
* @OA\MediaType(mediaType="application/json",
* @OA\Schema(
* @OA\Property(
* property="username",
* type="string"
* ),
* @OA\Property(
* property="password",
* type="string"
* ),
* @OA\Property(
* property="sex",
* type="integer",
* ),
* )
* )
* }),
* @OA\Response(
* response="200",
* description="状态码、提示消息",
* @OA\MediaType(mediaType="application/json",
* @OA\Schema(
* required={"code","message"},
* @OA\Property(
* property="code",
* type="integer",
* format="int32",
* description="状态码"
* ),
* @OA\Property(
* property="message",
* type="string",
* description="提示消息"
* )
* )
* )
* )
*)
*/本文把swagger3的常用用法做了一个记录，更加详细的使用说明请查看官方文档（About Swagger Specification | Documentation | Swagger）。
文章来源：0到1实现thinkphp6+swagger-php3.0配置管理接口文档 | 猿小莫的博客