TP5适用
例项目名称tp5
文件public下下载swagger-ui(只需要dist下的文件)
git clone https://github.com/swagger-api/swagger-ui.git
然后打开下载好的文件夹,找到dist目录, 打开index.html把其中的那一串url改成自己的url,就是第一步中的创建好的那个url,记得后面加上swagger.json,即http://localhost/tp5/swagger-ui/swagger.json
<script>
window.onload = function() {
// Build a system
const ui = SwaggerUIBundle({
url: "http://localhost/tpSwagger/tp5/swaggerApi/swagger.json", // 更改此url为你的url
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})
window.ui = ui
}
</script>
改完之后,访问下你的swagger-ui中index所在的url:http://localhost/tp5/swagger-ui/index.html,显示的内容应该为:Failed to load spec.
安装swagger-php后端(第三方类)
进入tp框架找到根目录下的composer.json,打开它并向其中的require中添加:
(tp5用的 "zircote/swagger-php": "^3.0" )
// 找到此文件的require,在后面直接添加
"zircote/swagger-php": "*"
// 添加前
"require": {
"php": ">=5.4.0",
"topthink/framework": "^5.0",
},
// 添加后
"require": {
"php": ">=5.4.0",
"topthink/framework": "^5.0",
"zircote/swagger-php": "*"
},
然后进入到此目录下(在此目录下shift+右键,选择在此处打开命令窗口),运行
composer update
等待安装完成或者直接在打开命令窗口之后运行
composer require zircote/swagger-php
提示安装完成后执行
composer global require zircote/swagger-php
会在你tp项目的vendor中生成一个zircote的组件文件夹,说明已经安装插件成功了。
生成swagger.json文件(swagger-php3.0版本bin/openapi 之前版本为bin/swagger )
php D:/phpstudy/WWW/tp5/vendor/zircote/swagger-php/bin/openapi D:/phpstudy/WWW/tp5/vendor/zircote/swagger-php/Examples -o D:/phpstudy/WWW/tp5/public/swagger-ui/swagger.json
(坑)tp5执行报错(think-captcha 12行)
composer更新topthink/think-captcha类
找到根目录下的composer.json,删除topthink/think-captcha类,打开命令框执行
composer require topthink/think-captcha
安装成功后再次执行生成swagger.json文件命令
ThinkPHP5中直接使用swagger
在tp5中写一个公用的方法,每次访问页面就直接调用此方法生成swagger.json文件,然后跳转到swagger的页面。首先把D:/phpstudy/WWW/tp5/vendor/zircote/swagger-php/Examples中的例子复制到你的application中,这样你的项目中就有了写好的可以测试的文件;然后写控制器中的方法:
<?php
namespace app\index\controller;
use think\Controller;
class Index extends Controller
{
public function index(){
$path = 'D:/phpstudy/WWW/tp5/application'; //你想要哪个文件夹下面的注释生成对应的API文档
//(坑 3.0后Swagger变为openapi新本版需要转json化 原语句:$swagger = \Swagger\scan($path);)
$swagger = \openapi\scan($path);
$swagger = json_encode($swagger);
// header('Content-Type: application/json');
// echo $swagger;
$swagger_json_path = 'D:/phpstudy/WWW/tp5/public/swagger-ui/swagger.json';
$res = file_put_contents($swagger_json_path, $swagger);
if ($res == true) {
$this->redirect('http://localhost/tp5/swagger-ui/index.html');
}
}
}
直接访问index方法,就会跳转到swagger的index.html 可以展示接口列表
备注写法
在你的class前⾯加⼊这样的⼀个代码
/**
* @OA\Info(
* title="Auth API",
* version="1.0"
* )
*/
这个是申明⽂档的标题及版本,注意:代码中只⽤加⼀个这个就可
/**
* @OA\Post(
* tags={"首页"}, //分组名称
* path="/index/banner", //接口地址
* summary="幻灯片", //接口名称
* @OA\RequestBody(
* @OA\MediaType(
* mediaType="application/json", //格式
* @OA\Schema(
* @OA\Property( //参数
* property="identity",
* type="string"
* ),
* @OA\Property( //参数
* property="type",
* type="string"
* ),
* example={"identity": 10,"type": 1} //参数示例
* )
* )
* ),
* @OA\Response( //响应数据
* response=200,
* description="OK"
* )
* )
*/
详细说明:版本说明 · Thinkphp集成Swagger-PHP · 看云
tp6引用
(加坑)更新完topthink/think-captcha类后再次执行生成swagger.json文件命令行运行报错'think\Console' not found
解决:把vendor/topthink/think-worker/src/command 下的 注释 掉
\think\Console::addDefaultCommands([
'worker:gateway' => '\\think\\worker\\command\\GatewayWorker',
'worker:server' => '\\think\\worker\\command\\Server',
'worker' => '\\think\\worker\\command\\Worker',
]);
然后在自己的应用里面的command.php 把下面这段复制进去数组
'worker:gateway' => '\\think\\worker\\command\\GatewayWorker',
'worker:server' => '\\think\\worker\\command\\Server',
'worker' => '\\think\\worker\\command\\Worker',
执行成功
tp6中使用swagger公用的方法报错,暂未解决