Swagger大大降低了接口提供者和接入者之间的沟通和维护成本，如果你还不了解Swagger的话，可以看我的另一篇文章《Laravel（PHP）使用Swagger生成API文档不完全指南 - 基本概念和环境搭建》
在PHP中使用Swagger，大多都会用到zircote/swagger-php这个Composer库。以Laravel项目为例，我们通常会为每个Controller的返回写一个单独的Swagger Definition以方便管理，然后在Controller的Annotation中写下这样的规则：
<?php
// ...
/**
* 假设是项目中的一个API
*
* @SWG\Get(path="/swagger/my-data",
* tags={"project"},
* summary="拿一些神秘的数据",
* description="请求该接口需要先登录。",
* operationId="getMyData",
* produces={"application/json"},
* @SWG\Parameter(
* in="formData",
* name="reason",
* type="string",
* description="拿数据的理由",
* required=true,
* ),
* @Swagger\Annotations\Schema(ref="#/definitions/MyDataResponse"),
* )
*/
public function getMyData()
{
//todo 待实现
}
// ...
而上面引用的MyDataResponse的定义看起来可能是这样：
<?php
/**
* @SWG\Definition
*/
class MyDataResponse
{
/**
* @var string
* @SWG\Property(example="Alan Jones")
*/
public $data;
}
注意，$data字段定义中设置了example属性，这实际上是给$data字段举了一个返回值的例子，这样不光可以把Swagger定义导入工具中做接口Mock（example即是Mock接口的返回值）、在Swagger UI返回格式同样也一目了然：
Property定义了example之后在Swagger UI中的显示效果
但有时这些简单的整型或者字符串example就无法满足项目需求了，例如你可能会需要返回这样一个数据结构：
{
"data": {
"current_level": 1,
"machine_detail": {
"sn": "77777777",
"mode": "extreme"
}
"records": [
{
"time": "2017-03-28 00:00:00",
"message": "machine started"
}
]
}
}
正常来讲，我们应该针对例子中的data、machine_detail和record（records中的每一个元素）分别建立Definition，然后在定义中去写引用（ref=）。但有时我们就是突然感觉很懒啊！又或者这些数据结构只有这一个接口使用，实在不值当单独定义几个Definition去实现啊（还是懒）！
那么怎么办呢？我简单总结了三个方法。
1. 直接把复杂结构写在example中
如下：
<?php
//...
/**
* @SWG\Property(
* example={"current_level": 1, [省略] "records": { { "time" [继续省略] } } },
* )
* @var object
*/
public $data;
//...
这种做法最大的坏处就是在注释中排版实在很痛苦……另外要注意得把JSON的数组括号（方括号）写成花括号（这是zircote/swagger-php的限制）。
2. 使用JSON文件定义
我们可以单独把这一个$data的Definition写在一个JSON文件中，如data.json，然后在注释（Annotation）中写一个引用：
<?php
//...
/**
* @SWG\Property(
* ref="data.json",
* )
*/
public $data;
//...
data.json内容为：
{
"current_level": 1,
"machine_detail": {
"sn": "77777777",
"mode": "extreme"
}
"records": [
{
"time": "2017-03-28 00:00:00",
"message": "machine started"
}
]
}
这样Swagger UI在加载完之后还会去请求data.json来获取定义内容，最终效果是一样的。但坏处是一部分Definition被拆到了另一个文件，一个JSON搞不定，而且请求多了也会慢。
3. 灵活使用zircote/swagger-php
让我们先回头看看是怎么使用zircote/swagger-php返回JSON格式Swagger 定义的：
<?php
// ...
/**
* @SWG\Swagger(
* @SWG\Info(
* title="我的`Swagger`API文档",
* version="1.0.0"
* )
* )
*/
public function getJSON()
{
$swagger = \Swagger\scan(app_path('Http/Controllers/'));
return response()->json($swagger, 200); //注意这一句我们直接把$swagger传给了json()方法
}
// ...
注意示例中的$swagger对象。
在调用\Swagger\scan()方法时，实际上是扫描你指定的所有目录和文件，将其中符合规则的Swagger Annotation解析出来，并转换为各种Class（在Swagger\Annotations名字空间下可以找到），最终这些Annotation对象都会被加载到$swagger对象里（Swagger\Annotations\Swagger）。$swagger是一个JsonSerializable，所以可以直接作为json_encode()函数的参数，在转换过程中，内部的各种定义对象就会被处理成一个可以JSON化的stdClass。
那么我们其实可以把最终生成的数据拿到，然后把复杂的定义直接写成PHP数组，在最后和$swagger转换结果中的definitions进行合并就可以了。之前也试过直接手动新建Swagger\Annotations\Definition对象，然后合并到$swagger->definitions数组中，但发现这写起来远没有直接写数组的效率高。
在项目中我将这些手写的Definition分文件存放，然后写了一个方法加载，最后合并到返回中。
上面例子的文件内容可以写成这样：
<?php
return [
"current_level" => 1,
"machine_detail" => [
"sn" => "77777777",
"mode" => "extreme"
]
"records" => [
[
"time" => "2017-03-28 00 =>00 =>00",
"message" => "machine started"
]
]
];
以及改过之后的getJSON()方法：
<?php
// ...
/**
* @SWG\Swagger(
* @SWG\Info(
* title="我的`Swagger`API文档",
* version="1.0.0"
* )
* )
*/
public function getJSON()
{
$swagger = \Swagger\scan(app_path('Http/Controllers/'));
return response()->json(
mergeWithRawDefinitions($swagger, loadRawDefinition(app_path('Swagger/Raw/'))),
200
);
}
// ...
本文仅仅是抛砖引玉，如果你有更“懒”的方法，欢迎在评论中与大家分享！
网友评论