Swagger PHP使用指南
先說什么是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下載
|
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-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'); }