先說什麼是Swagger, Swagger的使用目的是方便優美的呈現出介面API的各種定義, 生成API文件, 包括引數, 路徑之類. 有時後端改了API的引數或者其他設定, 前端直接看這個Swagger UI就可以, 方便專案管理和團隊協作.

官網: http://swagger.io/

引數文件: https://github.com/swagger-api/swagger-ui#parameters

這東西咋用呢? 說白了就是安裝Swagger套件, 然後API程式碼裡寫註釋, 用Swagger後端程式跑API來提取註釋, 生成一個json檔案, 再通關Swagger前端來美化,整理JSON資料.

要使用Swagger要安裝2個東西, 前段,用來顯示;後端, 用來生成JSON

##1, 安裝前段

swagger-ui下載

下載之後找到dist目錄, 開啟index.html把其中的那一串url改成自己的, 比如http://localhost/yii2/swagger-docs/swagger.json

$(function () {
      var url = window.location.search.match(/url=([^&]+)/);
      
 
if (url && url.length > 1) {
        url = decodeURIComponent(url[1]);
      } else {
        url = "http://localhost/yii2/swagger-docs/swagger.json";
      }

還可以把介面調整成中文, 放開js檔案的註釋即可

然後開啟URL就可以看到前端介面了, 應該是沒內容的, 因為還沒生成swagger.json, 生成好之後你設定的URL就起了作用, 直接訪問前端就好

http://localhost/yii2/swagger-ui/dist/index.html

##2, 安裝後端

因為我用的是yii2, 所以使用了composer來安裝

"require": { "zircote/swagger-php": "*" }

之後composer update, 或者直接命令列, 詳見https://github.com/zircote/swagger-php

DCdeMacBook-Pro:yii2 DC$ php composer.phar require zircote/swagger-php

我把swagger-php放在根目錄下，然後用官方提供的Examples來生成測試json

cd swagger-php
mkdir doc 
php swagger.phar Examples -o doc

"-o" 前面代表API源目錄, 即你想要生成哪個目錄的API文件, 你的專案程式碼目錄. "-o" 後面是生成到哪個path

我沒有進入到swagger-php下面, 直接打的命令列, 任意路徑下都可以執行生成json操作

php /Users/DC/www/yii2/vendor/zircote/swagger-php/bin/swagger /Users/DC/www/yii2/vendor/zircote/swagger-php/Examples -o /Users/DC/www/yii2/swagger-docs

然後再看http://localhost/yii2/swagger-ui/dist/index.html, 生成了API文件

準備工作都做好了, 那就寫程式碼註釋就行了, 註釋怎麼寫? 參考官方文件http://zircote.com/swagger-php/annotations.html

比如Model的

/**
* @SWG\Model(
* id="vps",
* required="['type', 'hostname']",
*  @SWG\Property(name="hostname", type="string"),
*  @SWG\Property(name="label", type="string"),
*  @SWG\Property(name="type", type="string", enum="['vps', 'dedicated']")
* )
*/
class HostVps extends Host implements ResourceInterface
{
    // ...
}

比如Controller的

/**
 * @SWG\Resource(
 *  basePath="http://skyapi.dev",
 *  resourcePath="/vps",
 *  @SWG\Api(
 *   path="/vps",
 *   @SWG\Operation(
 *    method="GET",
 *    type="array",
 *    summary="Fetch vps lists",
 *    nickname="vps/index",
 *    @SWG\Parameter(
 *     name="expand",
 *     description="Models to expand",
 *     paramType="query",
 *     type="string",
 *     defaultValue="vps,os_template"
 *    )
 *   )
 *  )
 * )
 */
 class VpsController extends Controller
 {
     // ...
 }

還看到一種整合把Swagger整合到Laravel中. Github地址是這個https://github.com/slampenny/Swaggervel，不過這個就不能用git clone方式去按照了，配置太麻煩，用composer吧

composer require "jlapp/swaggervel:dev-master"

下一步 Jlapp\Swaggervel\SwaggervelServiceProvider 複製這一句到 app/config/app.php 的 providers陣列最上面，然後

php artisan vender:publish

這一步把相關檔案包括swagger ui複製到laravel框架public下面。OK，已經好了，試著訪問根目錄下，比如 www.1.com/api-docs試試，出現介面就成功了！沒從先就用命令看下laravel的路由

php artisan route:list

最上面2條就是剛剛新增的路由。 重新整理頁面是不是發現空白？要生產json需要你寫@SWG的註釋，再laravel的app目錄下面任何檔案寫好就可以了，一般我們只需要寫model和controller的，這個外掛會掃描這個目錄生產json檔案。

=====================================

每次改動API程式碼註釋之後都要手動生成json檔案? 太麻煩了, 寫了個controller, 每次訪問swagger-ui的這個controller, 先生成json再跳轉到ui頁面

$b2broot = Yii::getAlias('@b2broot');
$swagger = \Swagger\scan($b2broot.'/myapi');
$json_file = $b2broot.'/swagger-docs/swagger.json';
$is_write = file_put_contents($json_file, $swagger);
if ($is_write == true) {
   $this->redirect('http://localhost/yii2/swagger-ui/dist/index.html');
}