Restler 3: Doc Comments

Doc Comments

You may use the following php doc comments to annotate your methods.

• @url
• @access
• @smart-auto-routing
• @class
• @cache
• @expires
• @throttle
• @status
• @header
• @param
• @throws
• @return

---

All tags except @url can also be defined at the class level.

@url

Overrides auto routes and creates manual routes. use as many as you need ###Syntax: @url GET|POST|PUT|PATCH|DELETE custom/{dynamic}/route ###Example: @url POST authors/{id}/books

---

@access

Access control for api methods. PHPDoc only supports private and public, Restler adds protected for api that needs authentication, hybrid for api that enhances resulting data for authenticated users.

Syntax:

@access private|public|protected|hybrid

###Example: POST authors/{id}/books

---

@smart-auto-routing

Smart auto routing is enabled by default. Avoids creating multiple routes that can increase the ambiguity when set to true. when a method parameter is optional it is not mapped to the url and should only be used in request body or as query string /resource?id=value. When a parameter is required and is scalar, it will be mapped as part of the url /resource/{id}

Syntax:

@smart-auto-routing true|false

Example: POST authors/{id}/books

---

##@class Inject property of the specified class with specified value

Syntax:

@class ClassName {@propertyName value}

###Example: @class AccessControl {@requires user} {@level 5}

---

##@cache Specify value to set CacheControl Header, it can use @expires value as shown in the example

Syntax:

@cache headerCacheControlValue

###Example: @cache max-age={expires}, must-revalidate

---

##@expires Sets the content to expire immediately when set to zero alternatively you can specify the number of seconds the content will expire

Syntax:

@expires numberOfSeconds

###Example: @expires 30

---

##@throttle Sets the time in milliseconds for bandwidth throttling, which will become the minimum response time for each API request.

Syntax:

@throttle numberOfMilliSeconds

###Example: @throttle 3000

---

##@status Sets the HTTP Status code for the successful response.

Syntax:

@status httpStatusCode

###Example: @status 201

---

##@header Sets or overrides the specific HTTP Header.

Syntax:

@header httpHeader

###Example: @header Link: <meta.rdf>; rel=meta

---

##@param Sets the HTTP Status code for the successful response

Syntax:

@param [type] Name [Description] {@name value}

###Example: @param int $num1 increment value {@min 5} {@max 100}

---

##@throws Documents possible error responses for the API call.

Syntax:

@throws httpStatusCode [Reason]

###Example: @throws 404 No Author for specified id

---

##@return Documents the structure of success response, user defined classes must extend iValueObject.

Syntax:

@return type [Description]

###Example: return Author an instance of iValueObject

---