*`resource`: whether the method describes a main resource or not (default: `false`);
*`description`: a description of the API method;
*`deprecated`: allow to set method as deprecated (default: `false`);
*`filters`: an array of filters;
*`requirements`: an array of requirements;
*`parameters`: an array of parameters;
*`input`: the input type associated to the method (currently this supports Form Types, classes with JMS Serializer
metadata, and classes with Validation component metadata) useful for POST|PUT methods, either as FQCN or as form type
(if it is registered in the form factory in the container).
*`output`: the output type associated with the response. Specified and parsed the same way as `input`.
*`statusCodes`: an array of HTTP status codes and a description of when that status is returned; Example:
``` php
<?php
class YourController
{
/**
*@ApiDoc(
* statusCodes={
* 200="Returned when successful",
* 403="Returned when the user is not authorized to say hello",
* 404={
* "Returned when the user is not found",
* "Returned when somehting else is not found"
* }
* }
* )
*/
public function myFunction()
{
// ...
}
}
```
Each _filter_ has to define a `name` parameter, but other parameters are free. Filters are often optional
parameters, and you can document them as you want, but keep in mind to be consistent for the whole documentation.
If you set `input`, then the bundle automatically extracts parameters based on the given type,
and determines for each parameter its data type, and if it's required or not.
For classes parsed with JMS metadata, description will be taken from the properties doc comment, if available.
For Form Types, you can add an extra option named `description` on each field:
``` php
<?php
class YourType extends AbstractType
{
/**
* {@inheritdoc}
*/
public function buildForm(FormBuilder $builder, array $options)
{
$builder->add('note', null, array(
'description' => 'this is a note',
));
// ...
}
}
```
The bundle will also get information from the routing definition (`requirements`, `pattern`, etc), so to get the
best out of it you should define strict _method requirements etc.
### Other bundle annotations ###
Also bundle will get information from the other annotations:
*@FOS\RestBundle\Controller\Annotations\RequestParam - use as `parameters`
*@FOS\RestBundle\Controller\Annotations\QueryParam - use as `requirements` (when strict parameter is true), `filters` (when strict is false)
*@JMS\SecurityExtraBundle\Annotation\Secure - set `authentification` to true, `authenticationRoles` to the given roles
*@Sensio\Bundle\FrameworkExtraBundle\Configuration\Cache - set `cache`
### PHPDoc ###
Route functions marked as @deprecated will be set method as deprecation in documentation.
#### JMS Serializer features ####
The bundle has support for some of the JMS Serializer features and use these extra information in the generated documentation.
##### Group Exclusion Strategy #####
If your classes use [JMS Group Exclusion Strategy](http://jmsyst.com/libs/serializer/master/cookbook/exclusion_strategies#creating-different-views-of-your-objects),
you can specify which groups to use when generating the documentation by using this syntax :
```
input={
"class"="Acme\Bundle\Entity\User",
"groups"={"update", "public"}
}
```
In this case the groups 'update' and 'public' are used.
This feature also works for the `output` property.
##### Versioning Objects #####
If your `output` classes use [versioning capabilities of JMS Serializer](http://jmsyst.com/libs/serializer/master/cookbook/exclusion_strategies#versioning-objects),
the versioning information will be automatically used when generating the documentation.
