Swagger 文檔管理

快速編寫你的 RESTFUL API 接口文檔工具，通過注釋定義接口和模型，可以和代碼文件放置一起，也可以單獨文件存放。

優勢

通過代碼注解定義文檔，更容易保持代碼文檔的一致性

模型復用，減少文檔冗余，帶來更可靠的文檔

提供客戶端訪問接口，可以直接調試接口，不需要第三方工具進行調用測試接口

支持權限認證，等功能

laravel Swagger 擴展

composer require darkaonline/l5-swagger

php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

將會生成配置文件 l5-swagger.php，其中需要注意的配置項

routes.api 默認值為 api/documentation Swagger 文檔系統訪問路由

routes.docs Swagger 解析注釋生成文檔 JSON 文件的存儲路徑

paths.annotations 有效注釋的路徑配置，默認 base_path('app') 應用路徑

generate_always 測試環境應該開啟這個配置，每次訪問都會自動解析注釋生成最新的文檔

swagger_version 這個默認為 2.0 , 建議修改為 3.0

下文所有的注釋內容，需要存在于 paths.annotations 路徑下。

接口版本

@OA\Info 定義接口版本，標題，描述，以及作者信息。

/**

* @OA\Info(

*      version="1.0",

*      title="用戶管理",

*      description="用戶模塊接口",

*      @OA\Contact(

*          name="PHP 開發支持",

*          email="dreamhelingfeng@gmail.com"

*      )

* )

*/

接口請求方式與請求路徑

@OA\Get,@OA\Post 定義接口請求方式

示例：根據USER_ID請求用戶詳情信息 /api/users/{user_id}

接口分組配置：tags，將會對接口歸類

/**

 * @OA\Get(

 *   path="/api/users/{user_id}",

 *   summary="根據 ID 獲取用戶信息",

 *   tags={"用戶管理"},

 *   @OA\Parameter(

 *     name="user_id",

 *     in="path",

 *     required=true,

 *     description="用戶 ID",

 *     @OA\Schema(

 *        type="string"

 *     )

 *   ),

 *   @OA\Response(

 *     response=200,

 *     description="用戶對象",

 *     @OA\JsonContent(ref="#/components/schemas/UserModel")

 *   )

 * )

 */

接口請求參數

通過 Swagger 可以定義三類參數，path,header,query

path, 參數存在 endponit 中，如，/users/{user_id}

header, 參數存在請求頭部，如，token 用戶校驗令牌

query, 請求參數帶在請求URL上，如，/users?nickname={nickname}

/**

 * @OA\Get(

 *   @OA\Parameter(

 *     name="user_id",

 *     in="path",

 *     required=true,

 *     description="用戶 ID",

 *     @OA\Schema(

 *        type="string"

 *     )

 * )

 */

POST 提交表單，通常使用 application/json 方式，如，創建用戶

@OA\Post

path=/users

/**

 *   @OA\RequestBody(

 *       @OA\MediaType(

 *           mediaType="application/json",

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

 *           example={

 *              "username": "helingfeng", "age": "25"

 *           }

 *       )

 *   )

 */

Schema 模型定義

上面的注釋中，多次引用 @OA\Schema(ref="#/components/schemas/UserModel")

/**

* @OA\Schema(

*      schema="UserModel",

*      required={"username", "age"},

*      @OA\Property(

*          property="username",

*          type="string",

*          description="用戶名稱"

*      ),

*      @OA\Property(

*          property="age",

*          type="int",

*          description="年齡"

*      )

* )

*/

Laravel-Swagger 會自動根據您的注釋進行匹配

上傳文件接口示例

定義一個接口，接收上傳文件，并返回結果遠程文件地址

接口定義：

/**

 * @OA\Post(

 *   path="/api/files/upload",

 *   summary="文件上傳",

 *   tags={"文件上傳"},

 *   @OA\RequestBody(

 *       @OA\MediaType(

 *           mediaType="multipart/form-data",

 *           @OA\Schema(

 *              required={"upload_file"},

 *              @OA\Property(

 *                  property="upload_file",

 *                  type="file",

 *                  description="上傳文件"

 *              ),

 *           ),

 *       )

 *   ),

 *   @OA\Response(

 *     response=200,

 *     description="上傳成功",

 *     @OA\JsonContent(ref="#/components/schemas/UploadFileModel")

 *   ),

 *   @OA\Response(

 *     response="default",

 *     description="error",

 *     @OA\JsonContent(ref="#/components/schemas/ErrorModel")

 *   )

 * )

 */

模型定義：

/**

* @OA\Schema(

*      schema="UploadFileModel",

*      @OA\Property(

*          property="file_name",

*          type="string",

*          description="文件名，不包含路徑"

*      ),

*      @OA\Property(

*          property="file_path",

*          type="string",

*          description="文件路徑"

*      ),

*      @OA\Property(

*          property="file_url",

*          type="string",

*          description="URL鏈接，用于展示"

*      ),

*      @OA\Property(

*          property="file_size",

*          type="string",

*          description="文件大小，單位B"

*      ),

*      @OA\Property(

*          property="extension",

*          type="string",

*          description="文件擴展名"

*      )

* )

*/

需要權限認證的接口

一般對外網開放的接口，需要添加權限控制，Swagger 提供很好的支持

在 l5-swagger.php 配置文件中添加， crypt-token 定義請求頭部必須添加 token 作為權限校驗令牌。

'security' => [

   /*

   |--------------------------------------------------------------------------

   | Examples of Security definitions

   |--------------------------------------------------------------------------

   */

   'crypt-token' => [ // Unique name of security

       'type' => 'apiKey', // The type of the security scheme. Valid values are "basic", "apiKey" or "oauth2".

       'description' => 'A short description for security scheme',

       'name' => 'token', // The name of the header or query parameter to be used.

       'in' => 'header', // The location of the API key. Valid values are "query" or "header".

   ],

]

接口注釋中，添加對應的驗證方式：

/**

 * security={

 *    {"crypt-token": {}}

 * },

 */

以上就是“使用 laravel-Swagger 編寫接口文檔”的詳細內容，想要了解更多laravel教程歡迎關注編程學習網