1.首先swagger 的認(rèn)識(shí)
先說什么是Swagger, Swagger的使用目的是方便優(yōu)美的呈現(xiàn)出接口API的各種定義, 生成API文檔, 包括參數(shù), 路徑之類. 有時(shí)后端改了API的參數(shù)或者其他設(shè)置, 前端直接看這個(gè)Swagger UI就可以, 方便項(xiàng)目管理和團(tuán)隊(duì)協(xié)作.
官網(wǎng): http://swagger.io/
參數(shù)文檔: https://github.com/swagger-api/swagger-ui#parameters
這東西咋用呢? 說白了就是安裝Swagger套件, 然后API代碼里寫注釋, 用Swagger后端程序跑API來提取注釋, 生成一個(gè)json文件, 再通關(guān)Swagger前端來美化,整理JSON數(shù)據(jù).
就是一個(gè)api的管理工具,一種規(guī)范,為后端和客戶端做便利的一種工具杨幼。
2.安裝 后端 也就是 swagger-PHP
????composer require zircote/swagger-php?
執(zhí)行就可以了就下載下來了克婶,然后項(xiàng)目根目錄會(huì)增加一個(gè)vendor這里面就是所謂的 swagger-PHP
使用:
<?php
require("vendor/autoload.php");
$openapi = \OpenApi\scan('/path/to/project');
header('Content-Type: application/x-yaml');
echo $openapi->toYaml();
3.接下來就是怎么寫注釋 生成json 然后 ui 顯示
會(huì)看到里面好多@SWG 這樣的注釋(參考最新的文檔實(shí)例),這些就是文檔啦牵敷,這個(gè)插件會(huì)自動(dòng)提取這些注釋然后生成一個(gè)json文件,然后ui 就可以 讀取出來了。
4.生成json文件
方法1:? 我這里是寫了一個(gè)控制器/方法窟哺,直接訪問方法名獲取最新信息寫入到swagger.json里,然后在重定向到頁面技肩,如圖
方法2:? 當(dāng)然還有命令行的方法:
php /phpstudynew/www/swagger/vendor/zircote/swagger-php? /bin/swagger/phpstudynew/www/swagger/application/controllers -o? /phpstudynew/www/swagger/docs/json
-o前面是自動(dòng)獲取 整個(gè)文件夾下面所有的 注釋且轨,后面是生成的路徑,也是ui訪問的路徑虚婿,這個(gè)默認(rèn)好像是swagger.json就這樣成功了
5.安裝前端
swagger-ui下載?
git clone https://github.com/swagger-api/swagger-ui.git
下載之后找到dist目錄復(fù)制到自己項(xiàng)目一個(gè)可以訪問的位置, 打開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 = "你生成的swagger.json文件位置";? ? ?
?}
然后訪問了自己項(xiàng)目dist/index.html的頁面,就出現(xiàn)下面的界面
簡單寫了下實(shí)現(xiàn)swagger的方法旋奢,還待學(xué)習(xí),總之要看文檔學(xué)著把文檔把例子看好然痊,很多博客可能有時(shí)間關(guān)系 文檔都更新了至朗,所以注釋格式會(huì)出現(xiàn)錯(cuò)誤的現(xiàn)象,所以一定最先去參考文檔剧浸!锹引。