接口开发，tp5结合swagger-ui安装方法

今天看到老java用的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 看下效果吧~