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 请求，大大的方便！