Swagger PHP使用指南____PHP

Swagger PHP使用指南

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

官網是http://swagger.io/

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

 

 

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

##1, 安裝前段

swagger-ui下載

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

下載之後找到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檔案的注釋即可

1 2 3

<script src= 'lang/translator.js' type= 'text/javascript' ></script>    <!-- <script src= 'lang/ru.js' type= 'text/javascript' ></script> -->   <script src= 'lang/zh-cn.js' type= 'text/javascript' ></script>

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

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

##2, 安裝後端

1	git clone https: //github.com/zircote/swagger-php.git

因為我用的是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-phpmkdir 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');}

 

 

 

 

參考自 http://blog.didibird.com/2015/06/23/swagger-ui-tutorials-api-documentation-generation-artifact/