由于项目需要,TP6需要集成swagger,用于自动将API文档导入到apifox。
萌新小白第一次使用swagger,所有操作都是百度来的。现在整理出来,望大家少走弯路。
以下所有操作全部在windows11系统中操作的。
安装swagger-php扩展
composer require zircote/swagger-php
安装swagger-php前端组件
https://github.com/swagger-api/swagger-ui 下载完成后将代码复制到public目录下。 看别的帖子,只复制dist文件夹也行,我没试
自定义函数,用于执行swagger的方法
我这里使用的是tp的闭包路由,也可以写个接口,只要能通过URL访问到就可以。
// 当访问127.0.0.1/dev/swagger时,会自动使用该闭包路由,执行里面的闭包函数
Route::get('/swagger', function() {
$openapi = \OpenApi\Generator::scan([
'../app/apiadmin/controller',
'../app/apiweb/controller',
]);
header('Content-Type: application/json');
echo $openapi->toJson();
});
修改/swagger-ui/dist/index.html
打开public\swagger-ui\dist\index.html文件,修改其中的url,能执行到上面的自定义函数 听说加这2行代码可以把文档改成中文
<script src="lang/translator.js" type=‘text/javascript’>
</script><script src="lang/zh-cn.js" type=‘text/javascript’></script>
查看swagger文档
访问上面的index.html,会自动访问我刚才自定义的闭包路由,自动生成新的API文档。
如果出现错误提示,根据我有限的经验,注释语法出错了!
swagger注释语法
我是第一次使用swagger,费了2天的功夫,终于写了一个get请求的,一个post请求的 废话不多说,直接贴图
/**
* @OA\Get(
* path="/apiadmin/holiday/lists",
* tags={"OA/apiadmin/假期规则"},
* summary="假期规则列表",
* @OA\Parameter(name="token",required=true,in="header",description="访问令牌",@OA\Schema(type="string",default="")),
* @OA\Parameter(name="page",required=true,in="query",description="页码",@OA\Schema(type="number",default="1")),
* @OA\Parameter(name="page_size",in="query",description="每页几条数据,不填默认15",@OA\Schema(type="number",default="15")),
* @OA\Response(response="200",description="成功",
* @OA\JsonContent(
* @OA\Property(property="code",description="接口状态码 1成功|0失败",type="integer",),
* @OA\Property(property="msg",description="提示语",type="string",),
* @OA\Property(property="time",description="时间戳",type="integer",),
* @OA\Property(property="data",description="接口数据",type="object",required={"option","list"},
* @OA\Property(property="option",description="选项",type="object",
* required={"leave_employee_arr","scope_type_arr","leave_paid_arr",},
* @OA\Property(property="leave_employee_arr",description="请假权限",type="object",),
* @OA\Property(property="scope_type_arr",description="适用范围",type="object",),
* @OA\Property(property="leave_paid_arr",description="是否带薪",type="object",),
* ),
* @OA\Property(property="list",description="数据列表",type="object",
* @OA\Property(property="total",description="数据总条数",type="integer",),
* @OA\Property(property="per_page",description="每页多少条",type="integer",),
* @OA\Property(property="current_page",description="当前第几页",type="integer",),
* @OA\Property(property="last_page",description="共几页",type="integer",),
* @OA\Property(property="data",description="数据列表",type="array",
* @OA\Items(type="object",
* @OA\Property(property="id",description="数据ID",type="integer",),
* @OA\Property(property="tenant_id",description="所属组织ID",type="integer",),
* @OA\Property(property="create_time",description="创建时间",type="integer",),
* @OA\Property(property="update_time",description="最后更新时间",type="integer",),
* ),
* ),
* ),
* ),
* ),
* ),
* )
*/
/**
* @OA\Post(
* path="/apiadmin/holiday/save",
* tags={"OA/apiadmin/假期规则"},
* summary="保存假期规则",
* operationId="save_holiday",
* @OA\Parameter(name="token",required=true,in="header",description="访问令牌",@OA\Schema(type="string",default="")),
* @OA\RequestBody(
* @OA\MediaType(mediaType="application/x-www-form-urlencoded",
* @OA\Schema(type="object",required={"method","version","name","leave_employee","scope_type","leave_paid","leave_unit","leave_calculation","set_balance"},
* @OA\Property(property="method",type="string",description="操作类型 add|edit",example="add"),
* @OA\Property(property="version",type="number",description="数据版本号 新增的默认1 编辑的使用列表返回的值",example="1"),
* @OA\Property(property="id",type="number",description="数据ID 编辑时必传",example="1"),
* @OA\Property(property="name",type="string",description="名称",example="假期"),
* ),
* ),
* ),
* @OA\Response(response=200,description="操作成功",
* @OA\JsonContent(
* @OA\Property(property="code",description="接口状态码 1成功|0失败",type="integer",),
* @OA\Property(property="msg",description="提示语",type="string",),
* @OA\Property(property="time",description="时间戳",type="integer",),
* @OA\Property(property="date",description="接口数据",),
* ),
* ),
* )
*/
apifox
数据源URL填入刚才定义的函数路径,apifox会自动识别本地URL。 立即导入,接口文档就同步至项目中,其它人就可以看到了,确实是非常方便。 如果出现错误提示,根据我有限的经验,注释语法出错了! 留意一下接口目录和注释中的tags之间的关系 踩了2天坑,大概就这么多吧,都是泪啊。
|