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

2023-02-16 06:00:50

一、安裝swagger-php

composer require zircote/swagger-php

swagger-php提供了命令列工具，所以可以全域性安裝，然後把工具的路徑加到PATH裡去。

composer global require zircote/swagger-php

然後把zircote/swagger-php/bin 目錄加到PATH裡。這個東西本人用不到，就不研究了。

二、設定一個輸出api檔案資料的介面

a）、生成一個控制器： SwaggerController

b）、新增一個方法： getJSON()

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

有的文章裡寫 Swaggerscan()，但我這裡報錯，說找不到這個類。查了官方檔案，要用 OpenApiGenerator::scan()。有可能是新版本做了修改。

c）、設定路由

api.php 或者 web.php都行，路徑不同而已。本人選擇api.php。所以存取路徑要加個字首：/api。

Route::group(['prefix' => 'swagger'], function () {
    Route::get('json', [AppHttpControllersSwaggerController::class, 'getJSON']);
});

d）、測試存取

存取 http://localhost:8000/api/swagger/json 如果看到頁面正常輸出json，說明設定成功了。不然就按錯誤提示一項項去修改吧。

三、使用

GET方法

    /** 
     * @OAGet(
     *     tags={"資料管理"},
     *     summary="資料查詢",
     *     path="/api/data/search",
     *     @OAResponse(response="200", description="Display a listing of projects."),
     *     @OAParameter(
     *         description="資料名稱",
     *         in="query",
     *         name="name",
     *         required=false,
     *         @OASchema(type="string"),
     *     ),
     *     @OAParameter(
     *         description="狀態",
     *         in="query",
     *         name="status",
     *         required=false,
     *         @OASchema(type="integer"),
     *     ),
     *     @OAParameter(
     *         description="每頁記錄數",
     *         in="query",
     *         name="page-size",
     *         required=false,
     *         @OASchema(type="integer"),
     *     ),
     *     @OAParameter(
     *         description="當前頁碼",
     *         in="query",
     *         name="current-page",
     *         required=false,
     *         @OASchema(type="integer"),
     *     ),
     * )
     */

這裡面:

in 表示該引數出現在哪裡。 query的話就是用&拼在url後面; path 類似於 /api/data/search/{param} ; header就是包含在 request header裡；cookie 自然是放在cookie裡。

這個版本里formData, body這些都沒有了。

required 看名字就知道 true是必填項，false是選填項。

POST方法

    /** 
     * @OAPost(
     *     tags={"資料管理"},
     *     summary="新增資料",
     *     path="/api/data",
     *     @OAResponse(response="200", description="Display a listing of projects."),
     *     @OARequestBody(
     *         @OAMediaType(
     *             mediaType="x-www-form-urlencoded",
     *             @OASchema(
     *                 ref="#/components/schemas/DataModel",
     *             ),
     *         ),
     *     ),
     * )
     */

因為本人的前端程式碼post都是表單提交，所以這裡的post方法要用@OARequestBody。

@OAParameter是引數，是可以放到url上，但是post的表單提交，資料是不出現在url上的。

@OAMediaType 這個: x-www-form-urlencoded 表單提交；application/json 提交json格式的資料；multipart/form-data 檔案上傳；

     *             @OASchema(
     *                 ref="#/components/schemas/DataModel",
     *             ),

這個是關聯到一個已經定義好的schema上，省得使用相同資料的每個介面註釋裡都寫一遍。

這裡也可以單獨寫：

 * @OASchema(
 *   required={"name", "code"},
 *   @OAProperty(property="name", type="string", title="姓名", description="這是姓名"),
 *   @OAProperty(property="code", type="string", title="程式碼", description="這是程式碼"),
 *   @OAProperty(property="phone", type="string", title="電話", description="這是電話"),
 * ),

上面這樣，有多少個引數就寫多少個@OAProperty。

這裡的required是個陣列，寫在裡面的都是必填項。

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

四、顯示swagger ui

下載swagger ui的程式碼： https://github.com/swagger-api/swagger-ui/releases

解壓後，把目錄裡的dist目錄，複製到laravel的public目錄下面，改名為swagger-ui。檔名隨便取，不衝突就行。

找開這個swagger-ui目錄下的swagger-initializer.js，內容大概如下：

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這項。改成前面設的路由地址。這裡是 "/api/swagger/json"。

完成後存取 http://localhost:8000/swagger-ui/ 就能看到swagger形成的api檔案了。

到此這篇關於PHP使用Swagger生成好看的API檔案的文章就介紹到這了,更多相關PHP Swagger內容請搜尋it145.com以前的文章或繼續瀏覽下面的相關文章希望大家以後多多支援it145.com！

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

目錄

一、安裝swagger-php

二、設定一個輸出api檔案資料的介面

三、使用

四、顯示swagger ui

熱門文章