Annotations

Annotations are PHP comments (docblocks) containing doctrine style annotations. With the introduction of support of PHP Attributes as of PHP 8.1, annotations are now deprecated in favor of attributes.

::: tip Namespace Using a namespace alias simplifies typing and improves readability.

All annotations are in the OpenApi\Annotations namespace.

use OpenApi\Annotations as OA;

/**
 * [@OA](https://github.com/OA)\Info(...)
 */

:::

Since Annotations are technically PHP comments, adding use OpenApi\Annotations as OA; is strictly speaking not necessary. However, doctrine will be quite specific about whether an alias is valid or not.

swagger-php will automatically register the [@OA](https://github.com/OA) alias so all annotations can be used with the [@OA](https://github.com/OA) shortcut without any additional work.

Doctrine

Annotations are PHP comments (docblocks) containing doctrine style annotations.

::: info All documentation related to doctrine applies to annotations only. :::

Example:

<?php

use OpenApi\Annotations as OA;

/**
 * [@OA](https://github.com/OA)\Info(title="My First API", version="0.1")
 */
class OpenApi {}

class MyController {

    /**
     * [@OA](https://github.com/OA)\Get(
     *     path="/api/resource.json",
     *     [@OA](https://github.com/OA)\Response(response="200", description="An example resource")
     * )
     */
    public function resource() {
        // ...
    }
}

Escaping

::: tip Escaping double quotes Double quotes can be escaped by doubling them rather than using \

For example:

    [@OA](https://github.com/OA)\Schema(
       title="Request",
       schema="Request",
       example={
          "configuration":"{""formConfig"":123}"
       }
     )

:::

Arrays and Objects

Doctrine annotations support arrays, but use { and } instead of [ and ].

Doctrine also supports objects, which also use { and } and require the property names to be surrounded with ".

::: warning DON'T WRITE

/**
 * [@OA](https://github.com/OA)\Info(
 *   title="My first API",
 *   version="1.0.0",
 *   contact={
 *     "email": "support@example.com"
 *   }
 * )
 */

:::

This "works" but most objects have an annotation with the same name as the property, such as [@OA](https://github.com/OA)\Contact for contact:

::: tip WRITE

/**
 * [@OA](https://github.com/OA)\Info(
 *   title="My first API",
 *   version="1.0.0",
 *   [@OA](https://github.com/OA)\Contact(
 *     email="support@example.com"
 *   )
 * )
 */

:::

This also adds validation, so when you misspell a property or forget a required property, it will trigger a PHP warning.

For example, if you write emial="support@example.com", swagger-php would generate a notice with Unexpected field "emial" for [@OA](https://github.com/OA)\Contact(), expecting "name", "email", ...

Placing multiple annotations of the same type will result in an array of objects. For objects, the key is defined by the field with the same name as the annotation: response in a [@OA](https://github.com/OA)\Response, property in a [@OA](https://github.com/OA)\Property, etc.

/**
 * [@OA](https://github.com/OA)\Get(
 *   path="/products",
 *   summary="list products",
 *   [@OA](https://github.com/OA)\Response(
 *     response=200,
 *     description="A list with products"
 *   ),
 *   [@OA](https://github.com/OA)\Response(
 *     response="default",
 *     description="an ""unexpected"" error"
 *   )
 * )
 */

Results in

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

Constants

You can use constants inside doctrine annotations.

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

/**
 * [@OA](https://github.com/OA)\Server(url=API_HOST)
 */

:::tip Using the CLI you might need to include the php file with the constants using the --bootstrap options.

> openapi --bootstrap constants.php

:::