swagger-php 入门教程

Question

swagger-php 的目的是使用 phpdoc 注释来生成一个 swagger.json。

输出（To output）:

{
 "swagger": "2.0",
 "schemes": ["http"],
 "host": "example.com",
 "basePath": "/api"
}

写（Write）:

/**
 * @SWG\Swagger(
 *   schemes={"http"},
 *   host="example.com",
 *   basePath="/api"
 * )
 */

注意，教条注释支持数组，但是使用 { 和 } 而不是 [和 ]。

虽然教条也支持对象，但也使用 {和 }，要求将属性名用 “ 包围。

不要写（DON'T write）:

/**
 * @SWG\Swagger(
 *   info={
 *   "title"="My first swagger documented API",
 *   "version"="1.0.0"
 *   }
 * )
 */

但可以使用与属性同名的注释，例如 @SWG\Info 为 info：

/**
 * @SWG\Swagger(
 *   @SWG\Info(
 *   title="My first swagger documented API",
 *   version="1.0.0"
 *   )
 * )
 */

这增加了验证，因此当您误拼属性或忘记了所需的属性时，它将触发 php 警告。例如，如果你写 titel="My first ...，swagger-php 会产生一个 "Unexpected field "titel" for @SWG\Info(), expecting "title", ..." 的 notice。

使用变量注释

使用变量注释（Using variables in annotations）

你可以在教条注解中使用常数。

define("API_HOST", ($env === "production") ? "example.com" : "localhost");

/**
 * @SWG\Swagger(host=API_HOST)
 */

当您使用 CLI 时，您需要使用 --bootstrap 选项将php文件包含在其中。

$ swagger --bootstrap constants.php

注释的位置（Annotation placement）

您不应该将所有注释放在一个大的 @SWG\Swagger() 注释块中，而是将它们分散到整个代码库中。swagger-php 将扫描您的项目并将所有注释合并到一个 @SWG\Swagger 注释中。

最大好处是swagger-php提供文档贴近实现 api 的代码。

对象和数组（Arrays and Objects）

将同一类型的多个注释放置在一个对象数组中。对于对象，属性的约定是使用与注释相同的字段名：response 在 @SWG\Response，property 在 @SWG\Property，等等。

/**
 * @SWG\Get(
 *   path="/products",
 *   summary="list products",
 *   @SWG\Response(
 *   response=200,
 *   description="A list with products"
 *   ),
 *   @SWG\Response(
 *   response="default",
 *   description="an ""unexpected"" error"
 *   )
 * )
 */

生成（Generates）:

{
  "swagger": "2.0",
  "paths": {
  "/products": {
    "get": {
    "summary": "list products",
    "responses": {
      "200": {
      "description": "A list with products"
      },
      "default": {
      "description": "an \"unexpected\" error"
      }
    }
    }
  }
  },
  "definitions": []
}

Swagger-PHP 检测基于上下文的值（Swagger-PHP detects values based on context）

Swagger-PHP着眼于减少重复的注释上下文。

/**
 * @SWG\Definition()
 */
class Product {
  /**
   * The product name
   * @var string
   * @SWG\Property()
   */
  public $name;
}

结果（results in）:

{
  "swagger": "2.0",
  "definitions": {
  "Product": {
    "properties": {
    "name": {
      "type": "string",
      "description": "The product name"
    }
    }
  }
  }
}

如果你写成（As if you'd written）：

/**
 * The product name
 * @var string
 *
 * @SWG\Property(
 *   property="name",
 *   type="string",
 *   description="The product name"
 * )
 */
public $name;

不要重复自己（Don't Repeat Yourself）：

在请求或响应中，多个请求有一些重叠是很常见的。该规范通过使用 $ref S解决了大多数问题

/**
 * @SWG\Definition(
 *   definition="product_id",
 *   type="integer",
 *   format="int64",
 *   description="The unique identifier of a product in our catalog"
 * )
 */

结果（results in）:

{
  "swagger": "2.0",
  "paths": {},
  "definitions": {
    "product_id": {
      "description": "The unique identifier of a product in our catalog",
      "type": "integer",
      "format": "int64"
    }
  }
}

它本身什么都不做但是现在你可以用 json 的路径 #/definitions/product_id 来引用这篇文章

/**
 * @SWG\Property(ref="#/definitions/product_id")
 */
public $id;

要了解更多关于refs的技巧，请浏览 using-refs 示例。

Vendor 扩展（Vendor extensions）

该规范允许自定义属性（custom properties），只要它们以 “x-” 开头，所有的大小写 php 注释都有一个 x 属性，将展开为 “x-” 属性。

/**
 * @SWG\Info(
 *   title="Example",
 *   version=1,
 *   x={"some-name":"a-value", "another": 2}
 * )
 */

结果（results in）:

"info": {
  "title": "Example",
  "version": 1,
  "x-some-name": "a-value",
  "x-another": 2
},

例如，Amazon API网关（Amazon API Gateway）就利用了这些。