swagger-php 快速上手指南

Posted on Edited on In Disqus:

小结

swagger 学习用时2天，天宫一号预计在2018年03月31日到2018年04月01日坠落地球，碎片坠落地点未知。

天宫一号的坠落，可以说我朝近年的航天成果全灭。

报道断章取义…… 陨落只是时间问题。小额外汇貌似限制了，实际未测试。

使用DarkaOnLine/L5-Swagger可以在代码中以注释形势直接编写API文档非常方便。

注释中的语法要使用Swagger-php样式，SWAGGER VERSION 3.0

DarkaOnLine/L5-Swagger安装

项目使用的是laravel 5.5 对应 darkaonline/l5-swagger:5.5.*

1
composer require "darkaonline/l5-swagger:5.5.*"

复制设置与视图文件

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

SWAGGER VERSION 3.0支持

1
composer require "zircote/swagger-php:3.x-dev"

设置.env文件

L5_SWAGGER_GENERATE_ALWAYS=true为每次打开页面是都进行重新渲染，设计阶段非常好用。

1
2
SWAGGER_VERSION=3.0
L5_SWAGGER_GENERATE_ALWAYS=true

基础文件设置

基本用法

swagger-v3.php

用于设置一些基本API信息，在页面最上方显示。

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
31
/**
* @OAS\OpenApi(
*     @OAS\Info(
*         version="1.0.0",
*         title="Test Api",
*         description="描述",
*         termsOfService="https://Test.dev/terms/",
*         @OAS\contact(
*             email="test@test.dev",
*             name="test",
*             url="https://test.dev"
*         ),
*         @OAS\License(
*             name="Apache 2.0",
*             url="http://www.apache.org/licenses/LICENSE-2.0.html"
*         )
*     ),
*     @OAS\Server(
*         description="OpenApi host",
*         url="https://test.dev/api"
*     ),
*     @OAS\Server(
*         description="OpenApi host",
*         url="https://test.dev/api/v2"
*     ),
*     @OAS\ExternalDocumentation(
*         description="OpenApi host",
*         url="https://test.dev/api/Doc"
*     )
* )
*/

@OAS 为使用前缀，用于读取swagger的设置

名头 解释 是否必要 其他说明
OpenApi swagger 初始化 必要 唯一并位于全部设置最顶端
Info Api说明 必要 设置中的title与version为必要项
Server Api 前置路径 非必要 多连接时，可以并行设置
ExternalDocumentation 扩展文档 非必要 只能设置description与url
paths 连接地址 必要 可以在控制器位置设置
tags 主标签 必要 与laravel一起使用时，独立设置方便管理。可以设置name、description、ExternalDocumentation

tags.php

用于设置用户标签

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
/**
* @OAS\Tag(
*     name="2fa",
*     description="Google 2FA",
*     @OAS\ExternalDocumentation(
*         description="more",
*         url="https://test.test/docs"
*     )
* )
* @OAS\Tag(
*     name="store",
*     description="Access to Petstore orders"
* )
* @OAS\Tag(
*     name="user",
*     description="Operations about user"
* )
*/

path 部分

直接使用注释形势写入控制器

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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
/**
* @OAS\Get(
*     path="/test",                                 // API 路由地址
*     tags={"test"},                                // 对应Tag
*     sumary="get test doc",                        // API概要
*     description="get test doc more ........",     // API描述
*     operationId="test",                           // API请求时ID
*     deprecated=false,                             // API是否有效
*     @OAS\Server(                                  // 独立API连接设置 可以覆盖全局
*         description="Server host",                // 连接描述
*         url="https://test.dev/api"                // 连接地址
*     ),
*     @OAS\Parameter(                               // API参数, 非必要
*         name=”id“,                                // 参数名
*         in="query",                               // 参数位置 可以设置`query`、`header`、`path`、`cookie`
*         description="adout this id ......",       // 描述
*         required=true,                            // 是否必须填写，当in设置为path时，需要设置为true。
*         style="from",                             // 设置参数序列化类型，非必要，自动根据in值设置。
*         @OAS\Schema(
*             type="string",                        // 参数类型
*             example="test example",               // 参数例子
*         )
*     ),
*     @OAS\RequestBody(                             // 请求主体 content-type 下使用 适合传递多个参数
*         description="adout this id ......",       // 描述
*         required=false,                           // 是否必须填写,默认为false
*         @OAS\MediaType(                           // 请求数据结构
*             mediaType="application/json",         // application/json 结构
*             @OAS\Schema(
*                 type="string"
*                 ref="#/components/schemas/User"   // 可以载入设置完成的参数,区分大小写
*             ),
*             @OAS\Schema(
*                 @OAS\Property(                    // 多参数设置
*                     property="otp",               // 参数名称
*                     description="yubikey otp",    // 参数描述
*                     type="string",                // 参数类型
*                     example="cccccccccccccccccccccccccccccccccccccccccccc"
*                                                   // 参数例子
*                 )
*             )
*         ),
*         @OAS\MediaType(                           // 请求数据结构
*             mediaType="application/xml",          // application/xml 结构
*             @OAS\Schema(
*                 type="string"
*                 ref="#/components/schemas/User"   // 可以载入设置完成的参数,区分大小写
*             ),
*             @OAS\Schema(
*                 @OAS\Property(                    // 多参数设置
*                     property="otp",               // 参数名称
*                     description="yubikey otp",    // 参数描述
*                     type="string",                // 参数类型
*                     example="cccccccccccccccccccccccccccccccccccccccccccc"
*                                                   // 参数例子
*                     )
*             )		
*         )
*     ),
*     @OAS\Response(                                // 响应,必须设置
*         response=200,                             // 响应编号
*         description="successful operation",       // 响应描述
*         @OAS\Header(
*             header="X-Rate-Limit",                // 响应头
*             description="calls per hour allowed by the user",
*                                                   // 响应头描述
*             @OAS\Schema(
*                 type="integer",
*                 format="int32",
*                 default="64",                     // 默认
*                 example="12"                      // 例子
*             )
*         ),
*         @OAS\MediaType(                           // 响应数据结构
*             mediaType="application/json",
*             @OAS\Schema(
*                 @OAS\Property(
*                     property="message",           // 响应参数头
*                     description="Response message",
*                     type="string",                // 响应参数数据类型
*                     example="true"                // 响应参数例子
*                 )
*             ),
*         )
*     )
* )
*/

Model 数据参数

可以直接设置在class之上，使用ref="#/components/schemas/ClassName"可以直接引用。

swagger默认载入位置#/components/schemas/。

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
/**
 * @OAS\Schema(
 *     title="yubikey model",
 *     description="yubikey model",
 *     type="object",
 *     @OAS\Property(
 *         property="message",
 *         description="Response message",
 *         type="string",
 *         default="true",  
 *         example="true"
 *     ),
 *     @OAS\Property(
 *         property="status",
 *         description="Updated status",
 *         type="string",
 *         example="true"
 *     ),
 *     @OAS\Property(
 *         property="age",
 *         description="Updated status of the pet",
 *         type="integer",
 *         minimum="0"
 *     ),
 * )
 */

bitbeans/yubikey 的坑

控制器中不能正常获取Exception。所以不能使用下方代码

1
2
3
4
5
6
7
8
9
use YubiKey;

try {
	$yubikey_auth = Yubikey::verify(Input::get('otp'));
	$yubikey_params = Yubikey::getParameters();
	$yubikey_identity = Yubikey::getParameter('identity');
} catch (\Exception $exception) {
	$error = $exception->getMessage();
}

改写到App\Exceptions\Handler的render方法判断，使用Exception判断的packages不多。

1
2
3
4
5
6
switch($exception->getMessage()) {
    case 'REPLAYED_OTP':
    return response()->json(['message' => $exception->getMessage()]);
    case 'Could not parse Yubikey OTP':
    return response()->json(['message' => $exception->getMessage()]);
}

以上