ThinkPHP5使用Swagger-php

環境：Centos7.1

參考了網上的一些教程，過程有點曲折。參考教程地址：https://www.cnblogs.com/lyh940/p/7020576.html

開始操作：

1、用composer安裝Swagger。

機器上裝的有寶塔面板，為了省事兒，直接用面板的shell執行安裝Swagger的命令，

curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer

我這邊執行之后，結果出現以下提示：

All settings correct for using Composer
The HOME or COMPOSER_HOME environment variable must be set for composer to run correctly

正常情況下，應當提示：

All settings correct for using Composer
download……

看到跟環境變量有關，就檢查了環境變量，發現查看環境變量的結果不正確。然后想到，也許不能使用寶塔面板的shell。於是登錄服務器，發現提示結果正常了。

 

composer安裝之后，發現全局命令無法使用。

composer update

composer require zircote/swagger-php

composer global require zircote/swagger-php

每次執行composer命令，都會提示命令參數。意思是我輸入的命令不對。

但是我明明進行了全局安裝。也就是執行了前面的mv命令。進入到usr/local/bin/目錄，發現文件也是在的。這就奇怪了。

使用composer -v命令，查看軟件的版本。發現是v0.2.x，版本好像不太對，查看了一下composer網站上的版本，發現當前官網上寫的是Latest: v1.8.0

難道有個軟件使用的命令跟composer重名？

上面提示執行這個命令，提示命令參數，於是我就用它提示的參數composer --help，查看幫助。發現給出的幫助里面，有個網址，訪問那個網址，發現是區塊鏈賬本項目介紹。原來是同事在這個服務器測試區塊鏈項目，裝的東西，沖突了。

 

想到能否給命令設置別名，於是將/usr/local/bin/composer改名為composer1。執行

composer1 install

提示權限被拒絕。難道是沒有權限？但是我明明使用的root賬號。還是去查看了composer1文件的權限，發現root有讀寫權限，但沒有執行權限，於是添加上執行權限，執行

composer1 install

執行成功。

 

 

2、下載swagger-ui

用cd命令進入到存放靜態文件的目錄，例如public目錄。執行下面命令：

git clone https://github.com/swagger-api/swagger-ui.git

 注意：上面的命令，下載的是當前最新版本3.0，但是3.0有個已知的問題，不支持中文。如果想支持中文，需要指定版本。

git clone --branch v2.2.10 https://github.com/swagger-api/swagger-ui.git

 

3、安裝swagger-php后端

進入tp框架找到根目錄下,打開composer.json找到require項，添加一行，然后使用更新命令。

"zircote/swagger-php": "*"

注意，每行用逗號分隔，不要忘了。

或者執行命令：

composer require "zircote/swagger-php"

注意：這個命令默認下載的是當前最新的版本，也就是3.x。我到git上查了一下，想要跟swagger-ui的2.x版本配合使用，需要使用swagger-php 2.x版本。指定版本：

composer require "zircote/swagger-php:2.0.13"

  

4、生成swagger.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

第1個路徑是你安裝成功后組件的路徑；

第2個路徑是你想要生成這個目錄下所有用swagger方式注釋的php文件，把所有注釋生成api文檔；

第3個路徑是你存放生成swagger.json的路徑。

可能是我這邊默認安裝的是新版的swagger（查看版本是3.0），提示找不到swagger

我到bin這個目錄，發現沒有swagger文件，但是有一個openapi文件。

於是就把bin/swagger改為bin/openapi，再次執行。

結果雖然報了很多警告，但是確實生成了json文件。

 

5、swagger-ui加載生成的json文件

進入到swagger-ui的下載目錄，找到dist目錄，打開里面的index.html文件，修改文件引用的.json文件的路徑為你的json文件的路徑（就是上面生成的那個swagger.json）

如果json文件的目錄設置不對，則會提示Failed to load API definition.

 

 6、快速更新文檔

<?php
namespace app\index\controller;

use think\Controller;
class Index extends Controller
{
    public function index(){
        $path = 'D:/WampServer/WWW/tpSwagger/tp5/application'; //你想要哪個文件夾下面的注釋生成對應的API文檔
        $swagger = \OpenApi\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');
        }
    }

}

我這邊在使用Swagger方法的時候，不能用這個\OpenApi\scan($path);提示找不到方法，需要用\Swagger\scan($path);

掃描的結果是對象，如果要寫入文件，需要轉換為字符串。另外在寫入文件的時候，遇到權限問題。我最后沒有使用file_put_contents函數

        $path = APP_PATH.'portal/test'; //你想要哪個文件夾下面的注釋生成對應的API文檔
        $swagger = \Swagger\scan($path);
        // header('Content-Type: application/json');
        // echo $swagger;
        $swagger_json_path = ROOT_PATH.'public/swaggerApi/swagger.json';
        // 檢測模板目錄
        $dir = dirname($swagger_json_path);
        if (!is_dir($dir)) {
            mkdir($dir, 0755, true);
        }

        $myfile = fopen($swagger_json_path, "w") or die("Unable to open file!");
        $swagger=json_encode($swagger, true);
        fwrite($myfile, $swagger);
        fclose($myfile);