• <menu id="imq0s"><strong id="imq0s"></strong></menu>
  • 福州網站建設>網站新聞>php技術

    Swagger-PHP api文檔詳細基礎教程

    發布日期:2022-03-17瀏覽次數:135 來源:福州網站建設

    1. 安裝Composer


    確認Composer是否已安裝,cmd窗口輸入命令:


    composer -V


    如果能看到版本號信息,說明Composer已經安裝,如圖:






    否則請自行下載安裝,下載地址:


    https://getcomposer.org/download/






    2. 安裝swagger-php


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


    composer require zircote/swagger-php






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






    3. 初始化swagger


    項目根目錄下新建一個子目錄,名稱為swagger-docs,然后切換到項目根目錄下,執行命令:


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


    成功后,目錄結構如下:






    4. 下載swagger-ui


    在swagger-ui官網下載靜態頁面,把靜態頁面放到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參數修改為swagger.json文件(第3步中初始化生成)的訪問地址即可,如圖:






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






    表示swagger已經搭建成功了,只不過展示的是示例文檔。


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


    多文檔的配置方式如下:


    同樣是修改swagger目錄下的index.html文件,將url參數注釋掉,然后增加urls參數,內容如下:


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






    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="行數",required=false),
    * @SWG\\Response(response="200", description="The User")
    * )
    */
    文檔編寫好后,我們需要重新執行初始化命令:


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


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


    參數說明


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


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


        summary 接口名稱


        description 接口詳細描述


        path 路由信息,即請求路徑


    @SWG\\Parameter 用來設置請求參數相關信息


    name 參數名稱


    type 參數類型,可選值有:


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


    in 參數的位置,即請求方式,可選值有:


            formData 表示是 post 請求的數據


            query 表示帶在 url 之后的參數,即get請求的參數


            path 表示請求路徑上的參數


            body 表示是一個 raw 數據請求


            header 表示帶在 header 信息中的參數


    description 參數描述


    required 定義該參數是否必須,可選值:true 或者 false


    default 參數的默認值


    @SWG\\Response 設置返回信息


    response 通常為狀態碼


    description 返回描述


    7. 訪問swagger


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


    即可看到如下界面:


    單文檔配置






    多文檔配置




    ————————————————
    版權聲明:本文為CSDN博主「木魚大叔」的原創文章,遵循CC 4.0 BY-SA版權協議,轉載請附上原文出處鏈接及本聲明。
    原文鏈接:https://blog.csdn.net/tdcqfyl/article/details/109673808
    php技術有關的文章
    如果您有什么問題,歡迎咨詢我們客服! 點擊QQ咨詢
    色妞网AV天堂,特级毛片高清特级毛片,免费欧洲毛片A级喷水视频软件
  • <menu id="imq0s"><strong id="imq0s"></strong></menu>