Swagger PHP使用指南

cnio 發布于2019-07-01 10:26 / 2184人閱讀

摘要：，已經好了，試著訪問根目錄下，比如試試，出現界面就成功了沒從先就用命令看下的路由最上面條就是剛剛添加的路由。

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

官網: http://swagger.io/

參數文檔: https://github.com/swagger-ap...

這東西咋用呢? 說白了就是安裝Swagger套件, 然后API代碼里寫注釋, 用Swagger后端程序跑API來提取注釋, 生成一個json文件, 再通關Swagger前端來美化,整理JSON數據.

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

1, 安裝前段

swagger-ui下載

1
git clone https://github.com/swagger-ap...
下載之后找到dist目錄, 打開index.html把其中的那一串url改成自己的, 比如http://localhost/yii2/swagger...

$(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

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

http://localhost/yii2/swagger...

2, 安裝后端

1
git clone https://github.com/zircote/sw...
因為我用的是yii2, 所以使用了composer來安裝

"require": { "zircote/swagger-php": "*" }
之后composer update, 或者直接命令行, 詳見https://github.com/zircote/sw...

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... 生成了API文檔

準備工作都做好了, 那就寫代碼注釋就行了, 注釋怎么寫? 參考官方文檔http://zircote.com/swagger-ph...

比如Model的

/**

@SWGModel(

id="vps",

required="["type", "hostname"]",

@SWGProperty(name="hostname", type="string"),

@SWGProperty(name="label", type="string"),

@SWGProperty(name="type", type="string", enum="["vps", "dedicated"]")

)

*/
class HostVps extends Host implements ResourceInterface
{

// ...

}

比如Controller的

/**

@SWGResource(

basePath="http://skyapi.dev",

resourcePath="/vps",

@SWGApi(

path="/vps",

@SWGOperation(

method="GET",

type="array",

summary="Fetch vps lists",

nickname="vps/index",

@SWGParameter(

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/...，不過這個就不能用git clone方式去按照了，配置太麻煩，用composer吧

composer require "jlapp/swaggervel:dev-master"
下一步 JlappSwaggervelSwaggervelServiceProvider 復制這一句到 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 = Swaggerscan($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...");
}

參考自 https://www.cnblogs.com/derrc...

文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。

轉載請注明本文地址：http://m.specialneedsforspecialkids.com/yun/29166.html

Swagger 生成 PHP restful API 接口文檔

摘要：需求和背景需求為客戶端同事寫接口文檔的各位后端同學已經在各種場合回憶了使用自動化文檔工具前手寫文檔的血淚史我的故事卻又不同因為首先來說我在公司是組負責人屬于上述血淚史中催死人不償命的客戶端陣營但血淚史卻是相通的沒有自動化文檔的日子對接口就是需求和背景需求: 為客戶端同事寫接口文檔的各位后端同學,已經在各種場合回憶了使用自動化文檔工具前手寫文檔的血淚史.我的故事卻又不同,因為首先來說...

xiaotianyi 2019-06-28 18:43 評論0 收藏0
Swagger 生成 PHP API 接口文檔

摘要：有同學推薦了，是一個簡單但功能強大的表達工具。這里介紹使用生成文檔的方法。將文檔輸出值的根目錄下，可通過訪問此文檔。執行結果如圖參考資料生成接口文檔如何編寫基于的文檔使用生成文檔不完全指南 Swagger 生成 PHP API 接口文檔標簽（空格分隔）： php 1、概況有同學反饋寫幾十個接口文檔需要兩天的工作量, 隨著多部門之間的協作越來越頻繁, 維護成本越來越高, 文檔的可維...

miya 2019-07-01 10:51 評論0 收藏0
Lumen微服務生成Swagger文檔

摘要：本文將會告訴你如何借助中插件，在開發微服務項目時項目和其它項目方法類似快速的在代碼中使用注釋來創建文檔。本文將會持續修正和更新，最新內容請參考我的上的程序猿成長計劃項目，歡迎，更多精彩內容請。框架配置我們使用當前最新的來演示。 showImg(https://segmentfault.com/img/remote/1460000017715535?w=1072&h=711); 作為一名...

alighters 2019-07-01 11:08 評論0 收藏0
swagger系列一：laravel中部署swagger ui

摘要：部署到項目中可以下來也可以下載文件。解壓后把目錄下的目錄拷貝到下下的文件夾中，如新建。訪問修改為自己的項目文件。找到，把修改為自己的，如，再次訪問即可。但是并不存在，需要生成。如放在下的目錄，用于存放文件。 1. 部署swagger ui 到項目中：可以Git下來 git clone https://github.com/swagger-api/swagger-uiv也可以下載zi...

lookSomeone 2019-06-28 18:39 評論0 收藏0
laravel使用手札——使用PHPStorm提升開發速度

摘要：安裝支持和請移步到使用手札。在安裝支持菜單欄搜索和安裝使用時可不用完全參照插件的備注方式，使用自動補全內容的格式便可以，即建設的備注格式在自動補全小結從官方文檔能看出對于支持可選和，經過試驗后發覺必須安裝才能很好地使用備注補全功能。 PHPStorm安裝 PHPStorm 使用手札——安裝看這里代碼自動提示支持 laravel引入laravel-ide-helper能為PHPStor...

caozhijian 2019-07-01 12:14 評論0 收藏0