欧美bbbwbbbw肥妇,免费乱码人妻系列日韩,一级黄片

PHP使用Swagger生成好看的API文檔

 更新時(shí)間:2023年02月15日 15:46:27   作者:HOOLOO  
api文檔不能根據(jù)代碼的變化發(fā)生實(shí)時(shí)動(dòng)態(tài)的改變,這樣后端修改了接口,前端不能及時(shí)獲取最新的接口,導(dǎo)致調(diào)用出錯(cuò),需要手動(dòng)維護(hù)api文檔,加大了開發(fā)的工作量和困難,而swagger的出現(xiàn)就是為了解決這一系列的問(wèn)題

PHP使用Swagger生成好看的API文檔不是不可能,而是非常簡(jiǎn)單。

首先本人使用Laravel框架,所以在Laravel上安裝swagger-php。

一、安裝swagger-php

composer require zircote/swagger-php

swagger-php提供了命令行工具,所以可以全局安裝,然后把工具的路徑加到PATH里去。

composer global require zircote/swagger-php

然后把zircote/swagger-php/bin 目錄加到PATH里。這個(gè)東西本人用不到,就不研究了。

二、設(shè)置一個(gè)輸出api文檔數(shù)據(jù)的接口

a)、生成一個(gè)控制器: SwaggerController

b)、添加一個(gè)方法: getJSON()

    public function getJSON()
    {
        $swagger = \OpenApi\Generator::scan([app_path('Http/Controllers/')]);
        return response()->json($swagger, 200);
    }

有的文章里寫 \Swagger\scan(),但我這里報(bào)錯(cuò),說(shuō)找不到這個(gè)類。查了官方文檔,要用 \OpenApi\Generator::scan()。有可能是新版本做了修改。

c)、設(shè)置路由

api.php 或者 web.php都行,路徑不同而已。本人選擇api.php。所以訪問(wèn)路徑要加個(gè)前綴:/api。

Route::group(['prefix' => 'swagger'], function () {
    Route::get('json', [\App\Http\Controllers\SwaggerController::class, 'getJSON']);
});

d)、測(cè)試訪問(wèn)

訪問(wèn) http://localhost:8000/api/swagger/json 如果看到頁(yè)面正常輸出json,說(shuō)明配置成功了。不然就按錯(cuò)誤提示一項(xiàng)項(xiàng)去修改吧。

三、使用

GET方法

    /** 
     * @OA\Get(
     *     tags={"數(shù)據(jù)管理"},
     *     summary="數(shù)據(jù)查詢",
     *     path="/api/data/search",
     *     @OA\Response(response="200", description="Display a listing of projects."),
     *     @OA\Parameter(
     *         description="數(shù)據(jù)名稱",
     *         in="query",
     *         name="name",
     *         required=false,
     *         @OA\Schema(type="string"),
     *     ),
     *     @OA\Parameter(
     *         description="狀態(tài)",
     *         in="query",
     *         name="status",
     *         required=false,
     *         @OA\Schema(type="integer"),
     *     ),
     *     @OA\Parameter(
     *         description="每頁(yè)記錄數(shù)",
     *         in="query",
     *         name="page-size",
     *         required=false,
     *         @OA\Schema(type="integer"),
     *     ),
     *     @OA\Parameter(
     *         description="當(dāng)前頁(yè)碼",
     *         in="query",
     *         name="current-page",
     *         required=false,
     *         @OA\Schema(type="integer"),
     *     ),
     * )
     */

這里面:

in 表示該參數(shù)出現(xiàn)在哪里。 query的話就是用&拼在url后面; path 類似于 /api/data/search/{param} ; header就是包含在 request header里;cookie 自然是放在cookie里。

這個(gè)版本里formData, body這些都沒(méi)有了。

required 看名字就知道 true是必填項(xiàng),false是選填項(xiàng)。

POST方法

    /** 
     * @OA\Post(
     *     tags={"數(shù)據(jù)管理"},
     *     summary="添加數(shù)據(jù)",
     *     path="/api/data",
     *     @OA\Response(response="200", description="Display a listing of projects."),
     *     @OA\RequestBody(
     *         @OA\MediaType(
     *             mediaType="x-www-form-urlencoded",
     *             @OA\Schema(
     *                 ref="#/components/schemas/DataModel",
     *             ),
     *         ),
     *     ),
     * )
     */

因?yàn)楸救说那岸舜apost都是表單提交,所以這里的post方法要用@OA\RequestBody。

@OA\Parameter是參數(shù),是可以放到url上,但是post的表單提交,數(shù)據(jù)是不出現(xiàn)在url上的。

@OA\MediaType 這個(gè): x-www-form-urlencoded 表單提交;application/json 提交json格式的數(shù)據(jù);multipart/form-data 文件上傳;

     *             @OA\Schema(
     *                 ref="#/components/schemas/DataModel",
     *             ),

這個(gè)是關(guān)聯(lián)到一個(gè)已經(jīng)定義好的schema上,省得使用相同數(shù)據(jù)的每個(gè)接口注釋里都寫一遍。

這里也可以單獨(dú)寫:

 * @OA\Schema(
 *   required={"name", "code"},
 *   @OA\Property(property="name", type="string", title="姓名", description="這是姓名"),
 *   @OA\Property(property="code", type="string", title="代碼", description="這是代碼"),
 *   @OA\Property(property="phone", type="string", title="電話", description="這是電話"),
 * ),

上面這樣,有多少個(gè)參數(shù)就寫多少個(gè)@OA\Property。

這里的required是個(gè)數(shù)組,寫在里面的都是必填項(xiàng)。

其它方法都差不多,以后有用到了再記錄。

四、顯示swagger ui

下載swagger ui的代碼: https://github.com/swagger-api/swagger-ui/releases

解壓后,把目錄里的dist目錄,復(fù)制到laravel的public目錄下面,改名為swagger-ui。文件名隨便取,不沖突就行。

找開這個(gè)swagger-ui目錄下的swagger-initializer.js,內(nèi)容大概如下:

window.onload = function() {
  //<editor-fold desc="Changeable Configuration Block">
  // the following lines will be replaced by docker/configurator, when it runs in a docker-container
  window.ui = SwaggerUIBundle({
    url: "/api/swagger/json",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  });
  //</editor-fold>
};

主要是改 url這項(xiàng)。改成前面設(shè)的路由地址。這里是 "/api/swagger/json"。

完成后訪問(wèn) http://localhost:8000/swagger-ui/ 就能看到swagger形成的api文檔了。

到此這篇關(guān)于PHP使用Swagger生成好看的API文檔的文章就介紹到這了,更多相關(guān)PHP Swagger內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家!

相關(guān)文章

  • PHP安全下載文件的方法

    PHP安全下載文件的方法

    這篇文章主要介紹了PHP安全下載文件的方法,涉及PHP文件的編碼設(shè)置,轉(zhuǎn)換,判斷及下載的相關(guān)技巧,需要的朋友可以參考下
    2016-04-04
  • CodeIgniter與PHP5.6的兼容問(wèn)題

    CodeIgniter與PHP5.6的兼容問(wèn)題

    這篇文章主要介紹了CodeIgniter與PHP5.6的兼容問(wèn)題的處理方法,有需要的小伙伴可以參考下。
    2015-07-07
  • PHP錯(cuò)誤提示的關(guān)閉方法詳解

    PHP錯(cuò)誤提示的關(guān)閉方法詳解

    關(guān)閉PHP錯(cuò)誤腳本提示是程序上線了必須做的一件事情,就是不管程序怎么報(bào)錯(cuò)我們都不能讓錯(cuò)誤日志在服務(wù)器上給大家看到,下面我來(lái)總結(jié)兩種關(guān)閉PHP錯(cuò)誤腳本提示的具體方法
    2013-06-06
  • php限制ip地址范圍的方法

    php限制ip地址范圍的方法

    這篇文章主要介紹了php限制ip地址范圍的方法,涉及php操作IP地址的技巧,非常具有實(shí)用價(jià)值,需要的朋友可以參考下
    2015-03-03
  • PHP中比較兩個(gè)對(duì)象的幾種方式小結(jié)

    PHP中比較兩個(gè)對(duì)象的幾種方式小結(jié)

    在PHP中,比較兩個(gè)對(duì)象并不是一件直接明了的事情,因?yàn)閷?duì)象之間的比較通常依賴于它們的屬性和狀態(tài),而這些屬性和狀態(tài)可能非常復(fù)雜且多樣化,本文給大家總結(jié)了PHP中比較兩個(gè)對(duì)象的幾種方式,需要的朋友可以參考下
    2024-09-09
  • php版微信公眾號(hào)接口實(shí)現(xiàn)發(fā)紅包的方法

    php版微信公眾號(hào)接口實(shí)現(xiàn)發(fā)紅包的方法

    這篇文章主要介紹了php版微信公眾號(hào)接口實(shí)現(xiàn)發(fā)紅包的方法,結(jié)合實(shí)例形式分析了php版微信公眾號(hào)實(shí)現(xiàn)發(fā)紅包的接口調(diào)用方法與相關(guān)使用注意事項(xiàng),需要的朋友可以參考下
    2016-10-10
  • windows環(huán)境下php配置memcache的具體操作步驟

    windows環(huán)境下php配置memcache的具體操作步驟

    本篇文章是對(duì)windows環(huán)境下php配置memcache的具體操作步驟進(jìn)行了詳細(xì)的分析介紹,需要的朋友參考下
    2013-06-06
  • PHP中檢索字符串的方法分析【strstr與substr_count方法】

    PHP中檢索字符串的方法分析【strstr與substr_count方法】

    這篇文章主要介紹了PHP中檢索字符串的方法,結(jié)合實(shí)例形式分析了strstr與substr_count函數(shù)的功能與具體使用技巧,需要的朋友可以參考下
    2017-02-02
  • PHP獲取表單數(shù)據(jù)與HTML嵌入PHP腳本的實(shí)現(xiàn)

    PHP獲取表單數(shù)據(jù)與HTML嵌入PHP腳本的實(shí)現(xiàn)

    下面小編就為大家?guī)?lái)一篇PHP獲取表單數(shù)據(jù)與HTML嵌入PHP腳本的實(shí)現(xiàn)。小編覺(jué)得挺不錯(cuò)的,現(xiàn)在就分享給大家,也給大家做個(gè)參考。一起跟隨小編過(guò)來(lái)看看吧
    2017-02-02
  • 利用PHPExcel實(shí)現(xiàn)Excel文件的寫入和讀取

    利用PHPExcel實(shí)現(xiàn)Excel文件的寫入和讀取

    本篇文章主要介紹了利用PHPExcel實(shí)現(xiàn)Excel文件的寫入和讀取的相關(guān)知識(shí)。具有很好的參考價(jià)值。下面跟著小編一起來(lái)看下吧
    2017-04-04

最新評(píng)論