Swagger整合到ThinkPHP實踐

前言

程序員最怕寫接口文檔，以前的項目中都是手工寫，然後公佈在一個內部網址上，程序參數一修改，接口文檔再手工更新一次，很費神，有了Swagger，一切變得簡單化，只要把註釋寫好，Swagger將直接抓取註釋內容自動生成接口文檔，也讓開發流程變得標準化。

環境

Swagger-UI、Swagger-PHP、ThinkPHP3.2.3、CentOS 6.5
Swagger的使用需要安裝兩個模塊分別是Swagger-UI、Swagger-PHP，
在項目根目錄下建立Tools文件夾，將有關接口文檔的程序全部佈署在此文件夾下。

1、安裝swagger-ui前端

cd Tools #進入工具目錄
git clone https://github.com/swagger-api/swagger-ui.git #下載swagger-ui版本

2、修改swagger-ui配置

找到swagger-ui/dist目錄，打開index.html，修改swagger.json文件的路徑 把其中的那一串url改成自己的 比如http://petstore.swagger.io/v2/swagger.json
註釋掉：

//var url = window.location.search.match(/url=([^&]+)/);
//if (url && url.length > 1) {
     //  url = decodeURIComponent(url[1]);
//} else {
     //  url = "http://petstore.swagger.io/v2/swagger.json";
//}

在上面代碼之後新增：（Tools下新建swagger-docs/v1.8，v1.8即迭代版本號，以後迭代一次新建一個版本文件夾）

var url = document.location.protocol+'//'+document.domain+'/Tools/swagger-docs/v1.8/swagger.json'; #下面的程序將把最新的swagger.json文件生成到這裏

如果你想支持中文在index.html中加上

<script src='lang/translator.js' type='text/javascript'></script>
<script src='lang/zh-cn.js' type='text/javascript'></script><!--將en.js改成zh-cn.js-->

3、安裝swagger-php後端

cd Tools  #進入工具目錄
composer require zircote/swagger-php  #通過composer來安裝

4、手工生成swagger.json

php  /project_root/Tools/vendor/zircote/swagger-php/bin/swagger /project_root/Tools/vendor/zircote/swagger-php/Examples -o  /project_root/Tools/swagger-docs/v1.8/swagger.json

執行完後，在v1.8目錄下即可看到json文件。

5、動態生成swagger.json

爲了讓前端開發人員每次打開接口文檔，看到的都是最新的接口內容，我們必須讓這個swagger.json能自動生成。
假設我們的目錄結構是這樣的：project_root/Application/Api，也就是說這裏是我們每次請求接口的模塊，在Api\Controller\IndexController.class.php文件中寫一個doc()方法，用來動態生成swagger.json，然後跳轉到swagger-ui的呈現首頁（dist/index.html），代碼如下：

class IndexController extends Controller
{
    public function __construct()
    {
        parent::__construct();
    }

    /* 接口文檔入口 */
    public function doc()
    {
        $pet = I('get.pet', 0, 'int');
        $path = 1==$pet ? 'Tools/vendor/zircote/swagger-php/Examples' : 'Application/Api'; //如果需要看pet示例，帶參數pet=1即可
        $swagger = \Swagger\scan($path);
        //header('Content-Type: application/json');
        //echo $swagger;
        $swagger_path = 'Tools/swagger-docs/v1.8/swagger.json';
        $res = file_put_contents($swagger_path, $swagger);
        if (true == $res) {
            $this->redirect('/Tools/swagger-ui/dist/index.html');
        } else {
            echo 'swagger.json寫入失敗！';
        }
    }

}

以上代碼中調用了\Swagger\scan()，這個類需要自動加載，我們在入口文件中引入自動加載文件：

require './Tools/vendor/autoload.php';

到此便大功告成，我們可以通過網址訪問查看最新的接口文檔：http://www.xxx.com/api/index/doc

我們還需要在工作之餘學習Swagger的註釋寫法（可以去這裏逛逛editor.swagger.io），儘管麻煩了些，但工欲善其事，必先利其器，往後的項目接口文檔變得一勞永逸！

---