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.
- @SWG\Resource
- @SWG\Api
- @SWG\Operation
- @SWG\Parameter
- @SWG\ResponseMessage
- @SWG\Model
- @SWG\Property
- @SWG\Items
- @SWG\Authorization
- @SWG\Scope
- @SWG\Info
Attributes
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.
Attributes
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.
Attributes
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.
Attributes
Example Annotations
/**
* @SWG\ResponseMessage(code=404, message="Pet not found")
*/
Derived JSON
"responseMessages":[
{
"code":404,
"message":"Pet not found"
}
]
Allowable Use:
Enclosed within Operation.
Attributes
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
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
Example Annotations
use Swagger\Annotations as SWG;
/**
* @SWG\Model(id="Pet")
*/
class Pet
{
...
}
Derived JSON
"Pet":{
"id":"Pet",
"properties":{
...
}
}
Attributes
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.
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
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