swagger-php 3.0分目录扫描,API 文档神器 Swagger 介绍及在 PHP 项目中使用

Swagger 是我目前用过的最优秀的 Api Doc 协议没有之一。它与其他 Api Doc 协议(如apidocjs)最大的差别在于,Swagger 不仅仅可以定义 Api 的 Route / Request Param 和 Response,还可以定义 Definitions Object / Security Definitions Object 以及 Reference Object。

以一个电商项目为例,系统里有 商品(Product)和 订单(Order)两个 Model,其中 Order 有一个 product_id 字段用于关联对应的商品;有两个接口,一个是获取商品详情 /product/{product},另一个是获取订单详情 /order/{order},为了减少Api请求数量,在获取订单详情时我们希望同时返回对应的商品数据。

如果我们用 apidocjs 来写的话,会是类似下面的注释

/**

* @api {get} /product/:product Request Product information

* @apiName GetProduct

* @apiParam {Number} product Products unique ID.

* @apiSuccess {String} name Name of the Product.

* @apiSuccess {Number} price Price of the Product.

* @apiSuccess ... Others fields

*/

/**

* @api {get} /order/:order Request Order information

* @apiName GetOrder

* @apiParam {Number} order Orders unique ID.

* @apiHeader {String} Authorization Access Token.

* @apiSuccess {String} flow_no FlowNo of the Order.

* @apiSuccess {String} price Price of the Order.

* @apiSuccess {Object} product Product of the Order

* @apiSuccess {String} product.name Name of the Product.

* @apiSuccess {Number} product.price Price of the Product.

* @apiSuccess ... Others fields

*/

可以看到 Product 的字段在两个接口的注释里各写了一遍,这就很繁琐;另外一个更严重的问题是,如果未来 Product 表的字段发生了增减,我们需要去修改每一个会输出 Product 的接口的注释,更繁琐而且容易遗漏。

所以我们需要有一个可以定义 Model 字段的功能,这就是 Swagger 的 Definitions Object,我们事先将 Product 和 Order 定义成 Definitions Object:

Product:

type: object

properties:

id:

type: integer

name:

type: string

price:

type: integer

Order:

type: object

properties:

id:

type: integer

flow_no:

type: string

product:

$ref: '#/definitions/Product'

在定义 Order 的 product 字段时,我们使用了 $ref,也就是 Reference Object,这就是告诉 Swagger,Order 的product 字段指向了 Product 的定义。

再来看看 Route / Request Param 和 Response 在Swagger 中怎么写:

path:

/product/{product}:

get:

summary: Request Product information

parameters:

name: product

in: path

required: true

type: number

response:

'200':

description: Success

schema:

$ref: '#/definitions/Product'

/order/{order}:

get:

summary: Request Order information

parameters:

name: order

in: path

required: true

type: number

response:

'200':

description: Success

schema:

$ref: '#/definitions/Order'

通过 $ref 完美解决了增减字段需要修改多处的问题。

我在第一次使用 Swagger 的时候,虽然被其强大的定义功能所折服,却又对写 Swagger 文档极其的厌恶,因为官方提供的 Swagger Editor 速度不仅慢,还时不时出错,明明写对了文档格式非要告诉我有问题,只能刷新页面重新加载。

直到最近发现了一个项目 swagger-php,通过注释的方式来生成 JSON 格式的 Swagger 文档,只需要通过 \Swagger\scan() 函数扫描一个目录下所有 PHP 文件的注释 (可以创建一个完全只有注释的 php 文件来放一些与 request / response 并无直接关联的定义,比如 Security Definitions Object)。

有了 JSON 格式的文档之后,配合 Swagger UI 就可以展示出非常美观的 Api 文档了,可以看这个 Demo,还支持在文档页面直接发起 Api 请求,大大的方便!

  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值