mirror of
https://github.com/retailcrm/NelmioApiDocBundle.git
synced 2025-02-02 15:51:48 +03:00
90 lines
2.9 KiB
ReStructuredText
90 lines
2.9 KiB
ReStructuredText
Other Bundle 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
|
|
|
|
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``:
|
|
|
|
.. code-block:: 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`_.
|
|
|
|
.. _`JMS Group Exclusion Strategy`: http://jmsyst.com/libs/serializer/master/cookbook/exclusion_strategies#creating-different-views-of-your-objects
|
|
.. _`versioning capabilities of JMS Serializer`: http://jmsyst.com/libs/serializer/master/cookbook/exclusion_strategies#versioning-objects
|
|
.. _`built-in Handlers`: https://github.com/nelmio/NelmioApiDocBundle/tree/master/Extractor/Handler
|