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

Other Bundle Annotations

• PHPDoc
• JMS Serializer Features
  • Group Exclusion Strategy
  • Versioning Objects
• Form Types Features
• 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, 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, 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:

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:

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:

# 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.

---

back to index