NelmioApiDocBundle/Resources/doc/other-bundle-annotations.md

Other Bundle Annotations
------------------------

* [PHPDoc](#phpdoc)
* [JMS Serializer Features](#jms-serializer-features)
  - [Group Exclusion Strategy](#group-exclusion-strategy)
  - [Versioning Objects](#versioning-objects)
* [Form Types Features](#form-types-features)
* [Using Your Own Annotations](#using-your-own-annotations)

---

This bundle will get information from the following 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 `authentication` to true, `authenticationRoles` to the given roles

* `@Sensio\Bundle\FrameworkExtraBundle\Configuration\Cache` - set `cache`

### PHPDoc

Actions marked as `@deprecated` will be marked as such in the interface.

### JMS Serializer Features

The bundle has support for some of the JMS Serializer features and uses this
extra piece of 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 :

 ```php
 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.

### Form Types Features

Even if you use `FormFactoryInterface::createNamed('', 'your_form_type')` the
documentation will generate the form type name as the prefix for inputs
(`your_form_type[param]` ... instead of just `param`).

You can specify which prefix to use with the `name` key in the `input` section:

```php
input = {
 "class" = "your_form_type",
 "name" = ""
}
```

You can also add some options to pass to the form. You just have to use the `options` key:

```php
input = {
 "class" = "your_form_type",
 "options" = {"method" = "PUT"},
}
```


### Using Your Own Annotations

If you have developed your own project-related annotations, and you want to
parse them to populate the `ApiDoc`, you can provide custom handlers as
services. You just have to implement the
`Nelmio\ApiDocBundle\Extractor\HandlerInterface` and tag it as
`nelmio_api_doc.extractor.handler`:

```yaml
# app/config/config.yml
services:
    mybundle.api_doc.extractor.my_annotation_handler:
        class: MyBundle\AnnotationHandler\MyAnnotationHandler
        tags:
            - { name: nelmio_api_doc.extractor.handler }
```

Look at the built-in
[Handlers](https://github.com/nelmio/NelmioApiDocBundle/tree/master/Extractor/Handler).

---

[back to index](index.md)