Annotations — Swagger-PHP documentation

### Navigation

- next
- previous |
- Swagger-PHP documentation »

# Annotations

Note

This is the documentation for (older / unsupported) swagger-php v1.x
Go to the swagger-php v3.x documentation

    <?php

    use Swagger\Annotations as SWG;

    /**
     *
     * @SWG\Model(id="Pet")
     */
    class Pet
    {
        /**
         * @var Tag[]
         *
         * @SWG\Property(name="tags", type="array", items="$ref:Tag")
         */
        protected $tags = array();
    }

When properties are ommitted, swagger-php will try to detect their value. The name for the @SWGProperty in this example is not needed, because swagger-php would infer “tags” based on protected $tags after the annotation.

The use statement also optional when using `@SWG\` for annotations.

Tip! Mistype an attribute and a warning will be shown with the available attributes for that particular annotation.

## Annotation Hierarchy

    - @SWG\Resource
      - @SWG\Api
        - @SWG\Operation
          - @SWG\Parameter
          - @SWG\ResponseMessage

    - @SWG\Model
      - @SWG\Property
        - @SWG\Items

    - @SWG\Authorization
      - @SWG\Scope

    - @SWG\Info

## Resource

Attributes

- `apiVersion` the version this api is being rendered as
- `swaggerVersion` the swagger-docs version being rendered `2.0`
- `resourcePath` the HTTP URI path for the resource
- `basePath` the service root HTTP URI path
- Api []

Example Annotations

    use Swagger\Annotations as SWG;

    /**
     * @SWG\Resource(
     *     apiVersion="0.2",
     *     swaggerVersion="1.1",
     *     resourcePath="/pet",
     *     basePath="http://petstore.swagger.wordnik.com/api"
     * )
     */

Derived JSON

    {
        "apiVersion":"0.2",
        "swaggerVersion":"1.1",
        "basePath":"http://petstore.swagger.wordnik.com/api",
        "resourcePath":"/pet",
        "apis":[...],
        "models": [...]
    }

Allowable Use:

Recommended as file or class annotation.

## Api

Attributes

- `path`
- `description`
- Operation []

Example Annotation

    use Swagger\Annotations as SWG;

    /**
     *
     * @SWG\Api(
     *   path="/pet.{format}/{petId}",
     *   description="Operations about pets",
     *   @SWG\Operation(...,
     *      @SWG\Parameter(...),
     *      @SWG\ResponseMessage(...),
     *      @SWG\ResponseMessage(...)
     *   )
     * )
     */

Derived JSON

    {
        "path":"/pet.{format}/{petId}",
        "description":"Operations about pets",
        "operations":[
            ...
        ]
    }

Allowable Use:

Must be after or inside a Resource annotation. Recommended as method annotation.

## Operation

Attributes

- `method` GET|POST|DELETE|PUT|PATCH etc
- `summary` string
- `notes` string
- `type` the Model ID returned
- `nickname` string
- ResponseMessage []
- Parameter []

Example Annotations

    use Swagger\Annotations as SWG;

    /**
     * @SWG\Operation(
     *     method="GET", summary="Find pet by ID", notes="Returns a pet based on ID",
     *     type="Pet", nickname="getPetById", ...
     * )
     */

Derived JSON

    {
        "method":"GET",
        "summary":"Find pet by ID",
        "notes":"Returns a pet based on ID",
        "type":"Pet",
        "nickname":"getPetById",
        "parameters":[...],
        "responseMessages":[...]
    }

Allowable Use:

Enclosed within Api.

## ResponseMessage

Attributes

- `code`
- `message`

Example Annotations

    /**
     * @SWG\ResponseMessage(code=404, message="Pet not found")
     */

Derived JSON

    "responseMessages":[
        {
            "code":404,
            "message":"Pet not found"
        }
    ]

Allowable Use:

Enclosed within Operation.

## Parameter

Attributes

- `name`
- `description`
- `paramType` body|query|path
- `required` bool
- `allowMultiple` bool
- `type` scalar or Model|object
- `defaultValue`

Example Annotations

    use Swagger\Annotations as SWG;

    /**
     * @SWG\Parameter(
     *     name="petId",
     *     description="ID of pet that needs to be fetched",
     *     paramType="path",
     *     required=true,
     *     allowMultiple=false,
     *     type="string"
     * )
     */

Derived JSON

    {
        "name":"petId",
        "description":"ID of pet that needs to be fetched",
        "paramType":"path",
        "required":true,
        "allowMultiple":false,
        "type":"string"
    }

Allowable Use:

Enclosed within Operation

## Model

Note

The annotations parser will follow any extend statements of the current model class and include annotations from the base class as well, as long as the `Model` annotation is placed into the comment block directly above the class declaration. Be sure also to activate the parser in the base class with the appropriate annotations.

Attributes

- `id` the formal name of the Model being described. Defaults to the name of the class (excl. namespace).
- `required` the required properties. Example: required=”[‘id’,’name’]”

Example Annotations

    use Swagger\Annotations as SWG;

    /**
     * @SWG\Model(id="Pet")
     */
     class Pet
     {
        ...
     }

Derived JSON

    "Pet":{
        "id":"Pet",
        "properties":{
            ...
        }
    }

## Property

Attributes

- `name`
- `type`
- `description`
- Items

Example Annotations

    use Swagger\Annotations as SWG;

    /**
     * @SWG\Property(name="category",type="Category")
     */
     public $category;
     * @SWG\Property(
     *      name="status",type="string",
     *      enum="['available', 'pending', 'sold']",
     *      description="pet status in the store")
     */
     public $status;

Derived JSON

    "category":{
        "type":"Category"
    },
    "status":{
        "enum":["available", "pending", "sold"],
        "description":"pet status in the store",
        "type":"string"
    },

Allowable Use:

Enclosed within Model or as property annotation.

## Items

Note

The `Items` annotation defines an array type i.e. an array of integers, strings or `$ref` to another model type. References are defined with a $ref: preamble followed by the model ID name as defined within a Model annotation. The `@SWG\Items` annotation resides within a Property declaration.

Attributes

- `Type`

Example Annotations

    use Swagger\Annotations as SWG;

    class Pet
    {
        /**
         * @SWG\Property(name="photoUrls",type="array",@SWG\Items("string"))
         */
        public $photos;

        /**
         * @SWG\Property(name="tags",type="array",@SWG\Items("Tag"))
         */
        public $tags;

        }

Derived JSON

    "properties":{
        "tags":{
            "items":{
                "$ref":"Tag"
            },
            "type":"array"
        },
        "id":{
            "type":"integer",
            "format: "int64"
        },
        "category":{
            "type":"Category"
        },
        "status":{
            "enum":["available", "pending", "sold"]
            "description":"pet status in the store",
            "type":"string"
        },
        "name":{
            "type":"string"
        },
        "photoUrls":{
            "items":{
                "type":"string"
            },
            "type":"array"
        }
    }

Allowable Use:

Enclosed within: Property

### Navigation

- next
- previous |
- Swagger-PHP documentation »