入门（Getting started）

原文：Getting started 翻译：小虾米（QQ:509129）

入门（Getting started）

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）就利用了这些。

关于Swagger的更多信息（More information about Swagger）

要查看哪个输出映射到哪个注释签查看swagger-explained，这也包含了swagger 规范的片段