今天看到*ava用的swagger提供接口，美观好用，方便维护，不是写好接口之后再写接口文档，麻烦的要死。网上找了找结合php的方法，在此记录一下，以后再开发接口就可以方便很多了。 Swagger的使用目的是方便优美的呈现出接口API的各种定义, 生成API文档, 包括参数, 路径之类. 有时后端改了API的参数或者其他设置, 前端直接看这个Swagger UI就可以, 方便项目管理和团队协作。
swagger-ui的原理
安装Swagger套件, 然后php文件代码里写注释, 用Swagger后端程序跑来php文件中提取注释, 生成一个json文件, 再通过Swagger前端来美化，达到展示JSON数据的效果。
前提：
电脑上装好了composer和git，直接使用它们进行安装，方便快捷。、
我把tp5和swagger-ui都放在我的wampServer下www中的tpSwagger即：E:\WampServer\WWW\tpSwagger
一、安装ThinkPHP5
无论官网下载还是git、composer安装都可以，我直接用的composer安装，切换到tpSwagger下运行：
composer create-project topthink/think tp5 --prefer-dist
安装好之后，在tp5根目录下直接新建一目录swaggerApi，此目录的路径为：http：//localhost/tpSwagger/tp5/swaggerApi（ps：在此建文件夹的目的是为了之后安装swagger之后保存swagger.json文件，你可以保存在别的地方，其实swagger每次回去加载这个生成的swagger.json,生成接口页面。如果我讲的不明白，可以先按照我这个建一下，等装完之后你就明白了）
二、下载swagger-ui
切换到项目的目录，直接git下载swagger，我放的路径是：
git clone https://github.com/swagger-api/swagger-ui.git
然后打开下载好的文件夹，找到dist目录, 打开index.html把其中的那一串url改成自己的url，就是第一步中的创建好的那个url,记得后面加上swagger.json,即http://localhost/tpSwagger/tp5/swaggerApi/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/tpSwagger/swagger-ui/dist/index.html，显示的内容应该为：Failed to load spec.
继续配置~
三、安装swagger-php后端
进入tp框架找到根目录下的composer.json，打开它并向其中的require中添加：
// 找到此文件的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的组件文件夹，说明已经安装插件成功了。
四、生成composer.json文件
直接在命令行中输入：
php E:/WampServer/WWW/tpSwagger/tp5/vendor/zircote/swagger-php/bin/swagger E:/WampServer/WWW/tpSwagger/tp5/vendor/zircote/swagger-php/Examples -o E:/WampServer/WWW/tpSwagger/tp5/swaggerApi/swagger.json
然后你再刷新一下看看http://localhost/tpSwagger/swagger-ui/dist/index.html，就能看到啦~~~
第一个路径是你安装成功后组件的路径；第二个路径是你想要生成这个目录下所有用swagger方式注释的php文件，把所有注释生成api文档；第三个路径是你存放生成swagger.json的路径。
五、ThinkPHP5中直接使用swagger
在tp5中写一个公用的方法，每次访问页面就直接调用此方法生成swagger.json文件，然后跳转到swagger的页面。首先把E:/WampSwever/WWW/tpSwagger/tp5/vendor/zircote/swagger-php/Examples中的例子复制到你的application中，这样你的项目中就有了写好的可以测试的文件；然后写控制器中的方法：
<?php
namespace app\index\controller; use think\Controller;
class Index extends Controller
{
public function index(){
$path = 'D:/WampServer/WWW/tpSwagger/tp5/application'; //你想要哪个文件夹下面的注释生成对应的API文档
$swagger = \Swagger\scan($path);
// header('Content-Type: application/json');
// echo $swagger;
$swagger_json_path = 'D:/WampServer/WWW/tpSwagger/tp5/swaggerApi/swagger.json';
$res = file_put_contents($swagger_json_path, $swagger);
if ($res == true) {
$this->redirect('http://localhost/tpSwagger/swagger-ui/dist/index.html');
}
} }
直接访问index方法，就会跳转到swagger的index.html 看下效果吧~