接口開發，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 看下效果吧~