1. 安裝Composer


確認Composer是否已安裝，cmd窗口輸入命令：


composer -V


如果能看到版本號信息，說明Composer已經(jīng)安裝，如圖：






否則請自行下載安裝，下載地址：


https://getcomposer.org/download/






2. 安裝swagger-php


cmd窗口中，切換到TP5項目的根目錄，輸入命令：


composer require zircote/swagger-php






安裝成功后，vendor目錄下會自動生成zircote/swagger-php子目錄，如圖：






3. 初始化swagger


項目根目錄下新建一個子目錄，名稱為swagger-docs，然后切換到項目根目錄下，執(zhí)行命令：


php vendor/zircote/swagger-php/bin/swagger vendor/zircote/swagger-php/Examples -o swagger-docs/swagger.json


成功后，目錄結(jié)構(gòu)如下：






4. 下載swagger-ui


在swagger-ui官網(wǎng)下載靜態(tài)頁面，把靜態(tài)頁面放到thinkphp框架目錄里。


https://swagger.io/tools/swagger-ui/






或者直接通過github下載也行，下載地址：


https://github.com/swagger-api/swagger-ui






5. 集成swagger-ui到項目中


在TP5項目的public目錄下，新建一個子目錄，名稱為swagger，然后將swagger-ui-master.zip壓縮包中dist目錄下的文件復制到swagger目錄下，如圖：






然后，修改swagger目錄下的index.html文件，將里面的url參數(shù)修改為swagger.json文件（第3步中初始化生成）的訪問地址即可，如圖：






此時，如果訪問http://local.tpmanager:8090/public/swagger這個鏈接，將會看到如下界面：






表示swagger已經(jīng)搭建成功了，只不過展示的是示例文檔。


注意：以上的配置，其實是一個單文檔配置，所有的接口都會在一個json文件中，如果接口比較多的話，可以使用多文檔配置，給文檔進行分類。


多文檔的配置方式如下：


同樣是修改swagger目錄下的index.html文件，將url參數(shù)注釋掉，然后增加urls參數(shù)，內(nèi)容如下：


urls:[
 
    {url:"http://local.tpmanager:8090/swagger-docs/swagger.json",name:"前端文檔"},
 
    {url:"http://local.tpmanager:8090/swagger-docs/swagger-admin.json",name:"后端文檔"}
 
],
完整的內(nèi)容如下圖：






6. 編寫自己的文檔接口


6.1 編寫整個項目的文檔概述


隨便找一個Controller的類文件，在其上面添加如下注解：


/**
* @SWG\\Swagger(
* @SWG\\Info(
* title="API文檔",
* version="版本1.0",
* description="本文檔僅限于測試"
* )
* )
*/
如圖：






6.2 編寫具體的接口文檔


在Controller文件的方法上添加如下注解：


/**
* @SWG\\Post(
* path="/api/article",
* tags={"文章管理"},
* summary="文章列表",
* description="顯示頁面",
* @SWG\\Parameter(name="token", type="string", in="header", description="token"),
* @SWG\\Parameter(name="page", type="integer", in="formData", description="頁碼",required=false),
* @SWG\\Parameter(name="limit", type="integer", in="formData", description="行數(shù)",required=false),
* @SWG\\Response(response="200", description="The User")
* )
*/
文檔編寫好后，我們需要重新執(zhí)行初始化命令：


php vendor/zircote/swagger-php/bin/swagger application/api/controller -o swagger-docs/swagger.json


注意：該命令需要切換到項目根目錄下執(zhí)行，其中的application/api/controller，就是我們項目中控制器文件的目錄，swagger-docs/swagger.json是初始化時創(chuàng)建的swagger.json文件。


參數(shù)說明


@SWG\\Post 表示是一個Post請求


    tags 接口標簽名稱， 標簽可用于對接口進行邏輯分組


    summary 接口名稱


    description 接口詳細描述


    path 路由信息，即請求路徑


@SWG\\Parameter 用來設置請求參數(shù)相關(guān)信息


name 參數(shù)名稱


type 參數(shù)類型，可選值有：


        string、number、integer、boolean、array、或 file


in 參數(shù)的位置，即請求方式，可選值有：


        formData 表示是 post 請求的數(shù)據(jù)


        query 表示帶在 url 之后的參數(shù)，即get請求的參數(shù)


        path 表示請求路徑上的參數(shù)


        body 表示是一個 raw 數(shù)據(jù)請求


        header 表示帶在 header 信息中的參數(shù)


description 參數(shù)描述


required 定義該參數(shù)是否必須，可選值：true 或者 false


default 參數(shù)的默認值


@SWG\\Response 設置返回信息


response 通常為狀態(tài)碼


description 返回描述


7. 訪問swagger


打開瀏覽器，在地址欄中輸入http://local.tpmanager:8090/public/swagger


即可看到如下界面：


單文檔配置






多文檔配置




————————————————
版權(quán)聲明：本文為CSDN博主「木魚大叔」的原創(chuàng)文章，遵循CC 4.0 BY-SA版權(quán)協(xié)議，轉(zhuǎn)載請附上原文出處鏈接及本聲明。
原文鏈接：https://blog.csdn.net/tdcqfyl/article/details/109673808