# 入门（Getting started）

> 原文：[Getting started](https://github.com/zircote/swagger-php/blob/master/docs/Getting-started.md)\
> 翻译：小虾米（QQ:509129）

## 入门（Getting started）

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

输出（To output）:

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

写（Write）:

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

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

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

不要写（**DON'T** write）:

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

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

```php
/**
 * @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）

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

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

```php
/**
 * @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`，等等

```php
/**
 * @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）:

```php
{
  "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着眼于减少重复的注释上下文。

```php
/**
 * @SWG\Definition()
 */
class Product {

    /**
     * The product name
     * @var string
     * @SWG\Property()
     */
    public $name;
}
```

结果（results in）:

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

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

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

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

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

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

结果（results in）:

```php
{
    "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` 来引用这篇文章

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

要了解更多关于refs的技巧，请浏览 [using-refs](https://github.com/zircote/swagger-php/tree/master/Examples/using-refs) 示例。

### Vendor 扩展（Vendor extensions）

该规范允许自定义属性（[custom properties](http://swagger.io/specification/#vendorExtensions)），只要它们以 “x-” 开头，所有的大小写php注释都有一个 `x` 属性，将展开为 “x-” 属性。

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

结果（results in）:

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

例如，Amazon API网关（[Amazon API Gateway](http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html)）就利用了这些。

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

要查看哪个输出映射到哪个注释签查看[swagger-explained](http://bfanger.github.io/swagger-explained/)，这也包含了[swagger 规范](http://swagger.io/specification/)的片段