Lzh on GitHub
命名空间 (Namespace)
使用命名空间别名可以简化输入并提高可读性。
所有注解都在 OpenApi\Annotations 命名空间中。

因为注解在技术上是 PHP 注释，所以严格来说添加 use OpenApi\Annotations as OA; 并不是必需的。然而，Doctrine 会非常严格地判断别名是否有效。

swagger-php 会自动注册 @OA 别名，因此所有注解都可以使用 @OA 快捷方式，无需任何额外工作。

Doctrine

注解是包含 Doctrine 风格注解的 PHP 注释（docblocks）。

所有与 Doctrine 相关的文档仅适用于注解。

示例：

<?php
use OpenApi\Annotations as OA;

/**
 * @OA\Info(title="My First API", version="0.1")
 */
class OpenApi {}

class MyController {
    /**
     * @OA\Get(
     * path="/api/resource.json",
     * @OA\Response(response="200", description="An example resource")
     * )
     */
    public function resource() {
        // ...
    }
}

转义 (Escaping)

转义双引号
双引号可以通过重复双引号来转义，而不是使用 \。
例如：
@OA\Schema(
  title="Request",
  schema="Request",
  example={
    "configuration":"{""formConfig"":123}"
  }
)

数组和对象

Doctrine 注解支持数组，但使用 { 和 } 而不是 [ 和 ]。

Doctrine 也支持对象，同样使用 { 和 }，并且需要用双引号将属性名括起来。

不要这样写
/**
 * @OA\Info(
 * title="My first API",
 * version="1.0.0",
 * contact={
 * "email": "support@example.com"
 * }
 * )
 */

这样 “可以工作”，但大多数对象都有一个与属性同名的注解，例如 contact: 对应的 @OA\Contact：

要这样写
/**
 * @OA\Info(
 * title="My first API",
 * version="1.0.0",
 * @OA\Contact(
 * email="support@example.com"
 * )
 * )
 */

这种写法还增加了验证功能，当你拼错属性或忘记某个必需属性时，它会触发一个 PHP 警告。

例如，如果你写成 emial="support@example.com"，swagger-php 会生成一个通知，提示 Unexpected field "emial" for @OA\Contact(), expecting "name", "email", ...。

放置多个相同类型的注解将产生一个对象数组。对于对象，键由与注解同名的字段定义：@OA\Response 中的 response，@OA\Property 中的 property 等。

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

结果如下

openapi: 3.0.0
paths:
  /products:
    get:
      summary: "list products"
      responses:
        "200":
          description: "A list with products"
        default:
          description: 'an "unexpected" error'

常量 (Constants)

你可以在 Doctrine 注解中使用常量。

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

/**
 * @OA\Server(url=API_HOST)
 */
使用命令行工具时，你可能需要使用 --bootstrap 选项来包含定义常量的 php 文件。
> openapi --bootstrap constants.php