Swagger 文檔管理

官方網站：https://swagger.io/

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

優勢

  • 通過代碼注解定義文檔，更容易保持代碼文檔的一致性
  • 模型復用，減少文檔冗余，帶來更可靠的文檔
  • 提供客戶端訪問接口，可以直接調試接口，不需要第三方工具進行調用測試接口
  • 支持權限認證，等功能

Laravel Swagger 擴展

擴展源代碼地址：https://github.com/DarkaOnLine/L5-Swagger

1
2
 
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 定義接口版本，標題，描述，已經作者信息。

1
2
3
4
5
6
7
8
9
10
11
 
/**
 * @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，將會對接口歸類

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
 
/**
 * @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}
1
2
3
4
5
6
7
8
9
10
11
12
 
/**
 * @OA\Get(
 * @OA\Parameter(
 * name="user_id",
 * in="path",
 * required=true,
 * description="用戶 ID",
 * @OA\Schema(
 * type="string"
 * )
 * )
 */

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

@OA\Post
path=/users

1
2
3
4
5
6
7
8
9
10
11
 
/**
 * @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")

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
/**
 * @OA\Schema(
 * schema="UserModel",
 * required={"username", "age"},
 * @OA\Property(
 * property="username",
 * type="string",
 * description="用戶名稱"
 * ),
 * @OA\Property(
 * property="age",
 * type="int",
 * description="年齡"
 * )
 * )
 */

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

上傳文件接口示例

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

接口定義：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
 
/**
 * @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")
 * )
 * )
 */

 

模型定義：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
 
/**
 * @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="文件擴展名"
 * )
 * )
 */

訪問 api/documentation 效果如圖

demo1

try it out 上傳文件操作結果

demo2

需要權限認證的接口

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
 
'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".
 ],
]

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

1
2
3
4
5
 
/**
 * security={
 * {"crypt-token": {}}
 * },
 */

demo3

更多 Swagger3 定義字段描述，可以查看官方文檔：https://swagger.io/specification/#parameterObject