Swagger Document Management

Official Website: https://swagger.io/

Fast write your  RESTFUL API interface documentation tool, through annotations defined interfaces and models, and code files can be placed together or separately file storage.

Advantage

  • ?? By definition document annotation of code, the code easier to maintain the consistency of the document
  • Model reuse, reduce redundant documentation, more reliable documents
  • Provides client access interface, you can debug interface directly, without third-party tools to test interface call
  • Support certification authority, and other functions

Laravel Swagger extension

Extended source address: https://github.com/DarkaOnLine/L5-Swagger

1
2
 
composer require darkaonline/l5-swagger
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"

It will generate a configuration file  l5-swagger.php, which should be noted configuration items

  • routes.api The default value  api/documentation Swagger document routing system access
  • routes.docs Swagger parsing JSON document storage path file generated comments
  • paths.annotations Effective annotations path configuration, the default  base_path('app') application path
  • generate_always Test environment should enable this configuration, each visit will automatically parse the latest documentation generated comments
  • swagger_version The default is 2.0, the proposed revised to 3.0

Hereinafter all annotation content, a need exists in  paths.annotations the path.

Interface Version

@OA\Info Defined interface version, title, description, author information already.

1
2
3
4
5
6
7
8
9
10
11
 
/ ** 
* @OA \ Info ( 
* Version = "1.0", 
* title = "User Management", 
* the Description = "User Interface Module", 
* @OA \ Business Card ( 
* name = "PHP development support", 
* Email = "dreamhelingfeng @ gmail.com" 
*) 
*) 
* /

Path request interface to request a manner

@OA\Get, @OA\Post Define the interface mode request

Example: The USER_IDrequesting user before information  /api/users/{user_id}
Interface grouping configuration: tagswill be classified on the interface

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
 
/ ** 
 * @OA \ the Get ( 
* path = "/ API / Users / user_id {}", 
* Summary = "acquired according to the user ID information", 
* = {Tags "User Management"}, 
* @OA \ the Parameter ( 
name = * "user_id", 
* in = "path", 
* = required to true, 
* the Description = "user ID", 
* @OA \ Schema ( 
* of the type = "String" 
*) 
*), 
* @OA \ the Response ( 
the Response = 200 *, 
* the Description = "user object", 
* @OA \ JsonContent (ref = "# / Components / schemas / UserModel") 
*) 
*) 
* /

Request Interface parameters

Can be defined by three parameters Swagger, path, header,query

  • path, in the presence of endponit parameters, such as, / users / {user_id}
  • header, there is a request header parameter, such as, a user token verification token
  • query, with the request parameters in the request URL, as, / 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 submit the form, commonly used  application/json methods, such as creating user

@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