mirror of
https://github.com/retailcrm/NelmioApiDocBundle.git
synced 2025-02-02 15:51:48 +03:00
Merge pull request #814 from javiereguiluz/fix_813
Transformed documentation to RST format
This commit is contained in:
William Durand
commit
4a95c81914
@ -1,21 +0,0 @@
|
|||||||
Commands
|
|
||||||
--------
|
|
||||||
|
|
||||||
A command is provided in order to dump the documentation in `json`, `markdown`,
|
|
||||||
or `html`.
|
|
||||||
|
|
||||||
php app/console api:doc:dump [--format="..."]
|
|
||||||
|
|
||||||
The `--format` option allows to choose the format (default is: `markdown`).
|
|
||||||
|
|
||||||
For example to generate a static version of your documentation you can use:
|
|
||||||
|
|
||||||
php app/console api:doc:dump --format=html > api.html
|
|
||||||
|
|
||||||
By default, the generated HTML will add the sandbox feature if you didn't
|
|
||||||
disable it in the configuration. If you want to generate a static version of
|
|
||||||
your documentation without sandbox, use the `--no-sandbox` option.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
[back to index](index.md)
|
|
||||||
21
Resources/doc/commands.rst
Normal file
21
Resources/doc/commands.rst
Normal file
@ -0,0 +1,21 @@
|
|||||||
|
Commands
|
||||||
|
========
|
||||||
|
|
||||||
|
A command is provided in order to dump the documentation in ``json``, ``markdown``,
|
||||||
|
or ``html``.
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
$ php app/console api:doc:dump [--format="..."]
|
||||||
|
|
||||||
|
The ``--format`` option allows to choose the format (default is: ``markdown``).
|
||||||
|
|
||||||
|
For example to generate a static version of your documentation you can use:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
$ php app/console api:doc:dump --format=html > api.html
|
||||||
|
|
||||||
|
By default, the generated HTML will add the sandbox feature if you didn't
|
||||||
|
disable it in the configuration. If you want to generate a static version of
|
||||||
|
your documentation without sandbox, use the ``--no-sandbox`` option.
|
||||||
@ -1,141 +0,0 @@
|
|||||||
Configuration In-Depth
|
|
||||||
----------------------
|
|
||||||
|
|
||||||
* [API Name](#api-name)
|
|
||||||
* [Authentication Methods](#authentication-methods)
|
|
||||||
* [Section Exclusion](#section-exclusion)
|
|
||||||
* [Parsers](#parsers)
|
|
||||||
* [MOTD](#motd)
|
|
||||||
* [Caching](#caching)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### API Name
|
|
||||||
|
|
||||||
You can specify your own API name:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# app/config/config.yml
|
|
||||||
nelmio_api_doc:
|
|
||||||
name: My API
|
|
||||||
```
|
|
||||||
|
|
||||||
### Authentication Methods
|
|
||||||
|
|
||||||
You can choose between different authentication methods:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# app/config/config.yml
|
|
||||||
nelmio_api_doc:
|
|
||||||
sandbox:
|
|
||||||
authentication:
|
|
||||||
delivery: header
|
|
||||||
name: X-Custom
|
|
||||||
|
|
||||||
# app/config/config.yml
|
|
||||||
nelmio_api_doc:
|
|
||||||
sandbox:
|
|
||||||
authentication:
|
|
||||||
delivery: query
|
|
||||||
name: param
|
|
||||||
|
|
||||||
# app/config/config.yml
|
|
||||||
nelmio_api_doc:
|
|
||||||
sandbox:
|
|
||||||
authentication:
|
|
||||||
delivery: http
|
|
||||||
type: basic # or bearer
|
|
||||||
```
|
|
||||||
|
|
||||||
When choosing an `http` delivery, `name` defaults to `Authorization`, and the
|
|
||||||
header value will automatically be prefixed by the corresponding type (ie.
|
|
||||||
`Basic` or `Bearer`).
|
|
||||||
|
|
||||||
### Section Exclusion
|
|
||||||
|
|
||||||
You can specify which sections to exclude from the documentation generation:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# app/config/config.yml
|
|
||||||
nelmio_api_doc:
|
|
||||||
exclude_sections: ["privateapi", "testapi"]
|
|
||||||
```
|
|
||||||
|
|
||||||
Note that `exclude_sections` will literally exclude a section from your api
|
|
||||||
documentation. It's possible however to create multiple views by specifying the
|
|
||||||
`views` parameter within the `@ApiDoc` annotations. This allows you to move
|
|
||||||
private or test methods to a complete different view of your documentation
|
|
||||||
instead.
|
|
||||||
|
|
||||||
### Parsers
|
|
||||||
|
|
||||||
By default, all registered parsers are used, but sometimes you may want to
|
|
||||||
define which parsers you want to use. The `parsers` attribute is used to
|
|
||||||
configure a list of parsers that will be used:
|
|
||||||
|
|
||||||
```php
|
|
||||||
output={
|
|
||||||
"class" = "Acme\Bundle\Entity\User",
|
|
||||||
"parsers" = {
|
|
||||||
"Nelmio\ApiDocBundle\Parser\JmsMetadataParser",
|
|
||||||
"Nelmio\ApiDocBundle\Parser\ValidationParser"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
In this case the parsers `JmsMetadataParser` and `ValidationParser` are used to
|
|
||||||
generate returned data. This feature also works for both the `input` and
|
|
||||||
`output` properties.
|
|
||||||
|
|
||||||
Moreover, the bundle provides a way to register multiple `input` parsers. The
|
|
||||||
first parser that can handle the specified input is used, so you can configure
|
|
||||||
their priorities via container tags. Here's an example parser service
|
|
||||||
registration:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# app/config/config.yml
|
|
||||||
services:
|
|
||||||
mybundle.api_doc.extractor.custom_parser:
|
|
||||||
class: MyBundle\Parser\CustomDocParser
|
|
||||||
tags:
|
|
||||||
- { name: nelmio_api_doc.extractor.parser, priority: 2 }
|
|
||||||
```
|
|
||||||
|
|
||||||
### MOTD
|
|
||||||
|
|
||||||
You can also define your own motd content (above methods list). All you have to
|
|
||||||
do is add to configuration:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# app/config/config.yml
|
|
||||||
nelmio_api_doc:
|
|
||||||
# ...
|
|
||||||
motd:
|
|
||||||
template: AcmeApiBundle::Components/motd.html.twig
|
|
||||||
```
|
|
||||||
|
|
||||||
### Caching
|
|
||||||
|
|
||||||
It is a good idea to enable the internal caching mechanism on production:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# app/config/config.yml
|
|
||||||
nelmio_api_doc:
|
|
||||||
cache:
|
|
||||||
enabled: true
|
|
||||||
```
|
|
||||||
|
|
||||||
You can define an alternate location where the ApiDoc configurations are to be
|
|
||||||
cached:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# app/config/config.yml
|
|
||||||
nelmio_api_doc:
|
|
||||||
cache:
|
|
||||||
enabled: true
|
|
||||||
file: "/tmp/symfony-app/%kernel.environment%/api-doc.cache"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
[back to index](index.md)
|
|
||||||
132
Resources/doc/configuration-in-depth.rst
Normal file
132
Resources/doc/configuration-in-depth.rst
Normal file
@ -0,0 +1,132 @@
|
|||||||
|
Configuration In-Depth
|
||||||
|
======================
|
||||||
|
|
||||||
|
API Name
|
||||||
|
--------
|
||||||
|
|
||||||
|
You can specify your own API name:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
# app/config/config.yml
|
||||||
|
nelmio_api_doc:
|
||||||
|
name: My API
|
||||||
|
|
||||||
|
Authentication Methods
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
You can choose between different authentication methods:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
# app/config/config.yml
|
||||||
|
nelmio_api_doc:
|
||||||
|
sandbox:
|
||||||
|
authentication:
|
||||||
|
delivery: header
|
||||||
|
name: X-Custom
|
||||||
|
|
||||||
|
# app/config/config.yml
|
||||||
|
nelmio_api_doc:
|
||||||
|
sandbox:
|
||||||
|
authentication:
|
||||||
|
delivery: query
|
||||||
|
name: param
|
||||||
|
|
||||||
|
# app/config/config.yml
|
||||||
|
nelmio_api_doc:
|
||||||
|
sandbox:
|
||||||
|
authentication:
|
||||||
|
delivery: http
|
||||||
|
type: basic # or bearer
|
||||||
|
|
||||||
|
When choosing an ``http`` delivery, ``name`` defaults to ``Authorization``, and
|
||||||
|
the header value will automatically be prefixed by the corresponding type (ie.
|
||||||
|
``Basic`` or ``Bearer``).
|
||||||
|
|
||||||
|
Section Exclusion
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
You can specify which sections to exclude from the documentation generation:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
# app/config/config.yml
|
||||||
|
nelmio_api_doc:
|
||||||
|
exclude_sections: ["privateapi", "testapi"]
|
||||||
|
|
||||||
|
Note that ``exclude_sections`` will literally exclude a section from your api
|
||||||
|
documentation. It's possible however to create multiple views by specifying the
|
||||||
|
``views`` parameter within the ``@ApiDoc`` annotations. This allows you to move
|
||||||
|
private or test methods to a complete different view of your documentation
|
||||||
|
instead.
|
||||||
|
|
||||||
|
Parsers
|
||||||
|
-------
|
||||||
|
|
||||||
|
By default, all registered parsers are used, but sometimes you may want to
|
||||||
|
define which parsers you want to use. The ``parsers`` attribute is used to
|
||||||
|
configure a list of parsers that will be used::
|
||||||
|
|
||||||
|
output={
|
||||||
|
"class" = "Acme\Bundle\Entity\User",
|
||||||
|
"parsers" = {
|
||||||
|
"Nelmio\ApiDocBundle\Parser\JmsMetadataParser",
|
||||||
|
"Nelmio\ApiDocBundle\Parser\ValidationParser"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
In this case the parsers ``JmsMetadataParser`` and ``ValidationParser`` are used
|
||||||
|
to generate returned data. This feature also works for both the ``input`` and
|
||||||
|
``output`` properties.
|
||||||
|
|
||||||
|
Moreover, the bundle provides a way to register multiple ``input`` parsers. The
|
||||||
|
first parser that can handle the specified input is used, so you can configure
|
||||||
|
their priorities via container tags. Here's an example parser service
|
||||||
|
registration:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
# app/config/config.yml
|
||||||
|
services:
|
||||||
|
mybundle.api_doc.extractor.custom_parser:
|
||||||
|
class: MyBundle\Parser\CustomDocParser
|
||||||
|
tags:
|
||||||
|
- { name: nelmio_api_doc.extractor.parser, priority: 2 }
|
||||||
|
|
||||||
|
MOTD
|
||||||
|
----
|
||||||
|
|
||||||
|
You can also define your own motd content (above methods list). All you have to
|
||||||
|
do is add to configuration:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
# app/config/config.yml
|
||||||
|
nelmio_api_doc:
|
||||||
|
# ...
|
||||||
|
motd:
|
||||||
|
template: AcmeApiBundle::Components/motd.html.twig
|
||||||
|
|
||||||
|
Caching
|
||||||
|
-------
|
||||||
|
|
||||||
|
It is a good idea to enable the internal caching mechanism on production:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
# app/config/config.yml
|
||||||
|
nelmio_api_doc:
|
||||||
|
cache:
|
||||||
|
enabled: true
|
||||||
|
|
||||||
|
You can define an alternate location where the ApiDoc configurations are to be
|
||||||
|
cached:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
# app/config/config.yml
|
||||||
|
nelmio_api_doc:
|
||||||
|
cache:
|
||||||
|
enabled: true
|
||||||
|
file: "/tmp/symfony-app/%kernel.environment%/api-doc.cache"
|
||||||
@ -1,59 +0,0 @@
|
|||||||
Configuration Reference
|
|
||||||
-----------------------
|
|
||||||
|
|
||||||
``` yaml
|
|
||||||
nelmio_api_doc:
|
|
||||||
name: 'API documentation'
|
|
||||||
exclude_sections: []
|
|
||||||
default_sections_opened: true
|
|
||||||
motd:
|
|
||||||
template: 'NelmioApiDocBundle::Components/motd.html.twig'
|
|
||||||
request_listener:
|
|
||||||
enabled: true
|
|
||||||
parameter: _doc
|
|
||||||
sandbox:
|
|
||||||
enabled: true
|
|
||||||
endpoint: null
|
|
||||||
accept_type: null
|
|
||||||
body_format:
|
|
||||||
formats:
|
|
||||||
|
|
||||||
# Defaults:
|
|
||||||
- form
|
|
||||||
- json
|
|
||||||
default_format: ~ # One of "form"; "json"
|
|
||||||
request_format:
|
|
||||||
formats:
|
|
||||||
|
|
||||||
# Defaults:
|
|
||||||
json: application/json
|
|
||||||
xml: application/xml
|
|
||||||
method: ~ # One of "format_param"; "accept_header"
|
|
||||||
default_format: json
|
|
||||||
authentication:
|
|
||||||
delivery: ~ # Required
|
|
||||||
name: ~ # Required
|
|
||||||
|
|
||||||
# Required if http delivery is selected.
|
|
||||||
type: ~ # One of "basic"; "bearer"
|
|
||||||
custom_endpoint: false
|
|
||||||
entity_to_choice: true
|
|
||||||
swagger:
|
|
||||||
api_base_path: /api
|
|
||||||
swagger_version: '1.2'
|
|
||||||
api_version: '0.1'
|
|
||||||
info:
|
|
||||||
title: Symfony2
|
|
||||||
description: 'My awesome Symfony2 app!'
|
|
||||||
TermsOfServiceUrl: null
|
|
||||||
contact: null
|
|
||||||
license: null
|
|
||||||
licenseUrl: null
|
|
||||||
cache:
|
|
||||||
enabled: false
|
|
||||||
file: '%kernel.cache_dir%/api-doc.cache'
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
[back to index](index.md)
|
|
||||||
55
Resources/doc/configuration-reference.rst
Normal file
55
Resources/doc/configuration-reference.rst
Normal file
@ -0,0 +1,55 @@
|
|||||||
|
Configuration Reference
|
||||||
|
=======================
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
nelmio_api_doc:
|
||||||
|
name: 'API documentation'
|
||||||
|
exclude_sections: []
|
||||||
|
default_sections_opened: true
|
||||||
|
motd:
|
||||||
|
template: 'NelmioApiDocBundle::Components/motd.html.twig'
|
||||||
|
request_listener:
|
||||||
|
enabled: true
|
||||||
|
parameter: _doc
|
||||||
|
sandbox:
|
||||||
|
enabled: true
|
||||||
|
endpoint: null
|
||||||
|
accept_type: null
|
||||||
|
body_format:
|
||||||
|
formats:
|
||||||
|
|
||||||
|
# Defaults:
|
||||||
|
- form
|
||||||
|
- json
|
||||||
|
default_format: ~ # One of "form"; "json"
|
||||||
|
request_format:
|
||||||
|
formats:
|
||||||
|
|
||||||
|
# Defaults:
|
||||||
|
json: application/json
|
||||||
|
xml: application/xml
|
||||||
|
method: ~ # One of "format_param"; "accept_header"
|
||||||
|
default_format: json
|
||||||
|
authentication:
|
||||||
|
delivery: ~ # Required
|
||||||
|
name: ~ # Required
|
||||||
|
|
||||||
|
# Required if http delivery is selected.
|
||||||
|
type: ~ # One of "basic"; "bearer"
|
||||||
|
custom_endpoint: false
|
||||||
|
entity_to_choice: true
|
||||||
|
swagger:
|
||||||
|
api_base_path: /api
|
||||||
|
swagger_version: '1.2'
|
||||||
|
api_version: '0.1'
|
||||||
|
info:
|
||||||
|
title: Symfony2
|
||||||
|
description: 'My awesome Symfony2 app!'
|
||||||
|
TermsOfServiceUrl: null
|
||||||
|
contact: null
|
||||||
|
license: null
|
||||||
|
licenseUrl: null
|
||||||
|
cache:
|
||||||
|
enabled: false
|
||||||
|
file: '%kernel.cache_dir%/api-doc.cache'
|
||||||
@ -1,25 +0,0 @@
|
|||||||
DunglasApiBundle Support
|
|
||||||
------------------------
|
|
||||||
|
|
||||||
This bundle recognizes and documents resources exposed with
|
|
||||||
[DunglasApiBundle](https://github.com/dunglas/DunglasApiBundle).
|
|
||||||
|
|
||||||
Install NelmioApiDocBundle and the documentation will be automatically
|
|
||||||
available. To enable the sandbox, use the following configuration:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# app/config/config.yml
|
|
||||||
nelmio_api_doc:
|
|
||||||
sandbox:
|
|
||||||
accept_type: "application/json"
|
|
||||||
body_format:
|
|
||||||
formats: [ "json" ]
|
|
||||||
default_format: "json"
|
|
||||||
request_format:
|
|
||||||
formats:
|
|
||||||
json: "application/json"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
[back to index](index.md)
|
|
||||||
23
Resources/doc/dunglasapibundle.rst
Normal file
23
Resources/doc/dunglasapibundle.rst
Normal file
@ -0,0 +1,23 @@
|
|||||||
|
DunglasApiBundle Support
|
||||||
|
========================
|
||||||
|
|
||||||
|
This bundle recognizes and documents resources exposed with
|
||||||
|
`DunglasApiBundle`_.
|
||||||
|
|
||||||
|
Install NelmioApiDocBundle and the documentation will be automatically
|
||||||
|
available. To enable the sandbox, use the following configuration:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
# app/config/config.yml
|
||||||
|
nelmio_api_doc:
|
||||||
|
sandbox:
|
||||||
|
accept_type: "application/json"
|
||||||
|
body_format:
|
||||||
|
formats: [ "json" ]
|
||||||
|
default_format: "json"
|
||||||
|
request_format:
|
||||||
|
formats:
|
||||||
|
json: "application/json"
|
||||||
|
|
||||||
|
.. _`DunglasApiBundle`: https://github.com/dunglas/DunglasApiBundle
|
||||||
@ -1,15 +0,0 @@
|
|||||||
Frequently Asked Questions
|
|
||||||
--------------------------
|
|
||||||
|
|
||||||
### How can I remove the parameter `_format` sent in `POST` and `PUT` request?
|
|
||||||
|
|
||||||
``` yaml
|
|
||||||
nelmio_api_doc:
|
|
||||||
sandbox:
|
|
||||||
request_format:
|
|
||||||
method: accept_header
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
[back to index](index.md)
|
|
||||||
12
Resources/doc/faq.rst
Normal file
12
Resources/doc/faq.rst
Normal file
@ -0,0 +1,12 @@
|
|||||||
|
Frequently Asked Questions
|
||||||
|
==========================
|
||||||
|
|
||||||
|
How can I remove the parameter ``_format`` sent in ``POST`` and ``PUT`` request?
|
||||||
|
--------------------------------------------------------------------------------
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
nelmio_api_doc:
|
||||||
|
sandbox:
|
||||||
|
request_format:
|
||||||
|
method: accept_header
|
||||||
@ -1,95 +0,0 @@
|
|||||||
NelmioApiDocBundle
|
|
||||||
==================
|
|
||||||
|
|
||||||
The **NelmioApiDocBundle** bundle allows you to generate a decent documentation
|
|
||||||
for your APIs.
|
|
||||||
|
|
||||||
* [Installation](#installation)
|
|
||||||
* [Usage](#usage)
|
|
||||||
- [The `ApiDoc()` Annotation](the-apidoc-annotation.md)
|
|
||||||
- [Multiple API Documentation a.k.a. "Views"](multiple-api-doc.md)
|
|
||||||
- [Other Bundle Annotations](other-bundle-annotations.md)
|
|
||||||
- [Swagger Support](swagger-support.md)
|
|
||||||
- [DunglasApiBundle Support](dunglasapibundle.md)
|
|
||||||
- [Sandbox](sandbox.md)
|
|
||||||
- [Commands](commands.md)
|
|
||||||
* [Configuration In-Depth](configuration-in-depth.md)
|
|
||||||
* [Frequently Asked Questions](faq.md)
|
|
||||||
* [Configuration Reference](configuration-reference.md)
|
|
||||||
|
|
||||||
|
|
||||||
Installation
|
|
||||||
------------
|
|
||||||
|
|
||||||
Require the `nelmio/api-doc-bundle` package in your composer.json and update
|
|
||||||
your dependencies.
|
|
||||||
|
|
||||||
$ composer require nelmio/api-doc-bundle
|
|
||||||
|
|
||||||
Register the bundle in `app/AppKernel.php`:
|
|
||||||
|
|
||||||
```php
|
|
||||||
// app/AppKernel.php
|
|
||||||
public function registerBundles()
|
|
||||||
{
|
|
||||||
return array(
|
|
||||||
// ...
|
|
||||||
new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
|
|
||||||
);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Import the routing definition in `routing.yml`:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# app/config/routing.yml
|
|
||||||
NelmioApiDocBundle:
|
|
||||||
resource: "@NelmioApiDocBundle/Resources/config/routing.yml"
|
|
||||||
prefix: /api/doc
|
|
||||||
```
|
|
||||||
|
|
||||||
Enable the bundle's configuration in `app/config/config.yml`:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# app/config/config.yml
|
|
||||||
nelmio_api_doc: ~
|
|
||||||
```
|
|
||||||
|
|
||||||
The **NelmioApiDocBundle** requires Twig as a template engine so do not forget
|
|
||||||
to enable it:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# app/config/config.yml
|
|
||||||
framework:
|
|
||||||
templating:
|
|
||||||
engines: ['twig']
|
|
||||||
```
|
|
||||||
|
|
||||||
Usage
|
|
||||||
-----
|
|
||||||
|
|
||||||
The main problem with documentation is to keep it up to date. That's why the
|
|
||||||
**NelmioApiDocBundle** uses introspection a lot. Thanks to an annotation, it's
|
|
||||||
really easy to document an API method. The following chapters will help you
|
|
||||||
setup your API documentation:
|
|
||||||
|
|
||||||
* [The `ApiDoc()` Annotation](the-apidoc-annotation.md)
|
|
||||||
* [Multiple API Documentation a.k.a. "Views"](multiple-api-doc.md)
|
|
||||||
* [Other Bundle Annotations](other-bundle-annotations.md)
|
|
||||||
* [Swagger Support](swagger-support.md)
|
|
||||||
* [DunglasApiBundle Support](dunglasapibundle.md)
|
|
||||||
* [Sandbox](sandbox.md)
|
|
||||||
* [Commands](commands.md)
|
|
||||||
|
|
||||||
### Web Interface
|
|
||||||
|
|
||||||
You can browse the whole documentation at: `http://example.org/api/doc`.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### On-The-Fly Documentation
|
|
||||||
|
|
||||||
By calling an URL with the parameter `?_doc=1`, you will get the corresponding
|
|
||||||
documentation if available.
|
|
||||||
115
Resources/doc/index.rst
Normal file
115
Resources/doc/index.rst
Normal file
@ -0,0 +1,115 @@
|
|||||||
|
NelmioApiDocBundle
|
||||||
|
==================
|
||||||
|
|
||||||
|
The **NelmioApiDocBundle** bundle allows you to generate a decent documentation
|
||||||
|
for your APIs.
|
||||||
|
|
||||||
|
Installation
|
||||||
|
------------
|
||||||
|
|
||||||
|
Step 1: Download the Bundle
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
Open a command console, enter your project directory and execute the
|
||||||
|
following command to download the latest stable version of this bundle:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
$ composer require nelmio/api-doc-bundle
|
||||||
|
|
||||||
|
This command requires you to have Composer installed globally, as explained
|
||||||
|
in the `installation chapter`_ of the Composer documentation.
|
||||||
|
|
||||||
|
Step 2: Enable the Bundle
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
Then, enable the bundle by adding it to the list of registered bundles
|
||||||
|
in the ``app/AppKernel.php`` file of your project:
|
||||||
|
|
||||||
|
.. code-block:: php
|
||||||
|
|
||||||
|
<?php
|
||||||
|
// app/AppKernel.php
|
||||||
|
|
||||||
|
// ...
|
||||||
|
class AppKernel extends Kernel
|
||||||
|
{
|
||||||
|
public function registerBundles()
|
||||||
|
{
|
||||||
|
$bundles = array(
|
||||||
|
// ...
|
||||||
|
new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
|
||||||
|
);
|
||||||
|
|
||||||
|
// ...
|
||||||
|
}
|
||||||
|
|
||||||
|
// ...
|
||||||
|
}
|
||||||
|
|
||||||
|
Step 3: Register the Routes
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
Import the routing definition in ``routing.yml``:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
# app/config/routing.yml
|
||||||
|
NelmioApiDocBundle:
|
||||||
|
resource: "@NelmioApiDocBundle/Resources/config/routing.yml"
|
||||||
|
prefix: /api/doc
|
||||||
|
|
||||||
|
Step 4: Configure the Bundle
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
Enable the bundle's configuration in ``app/config/config.yml``:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
# app/config/config.yml
|
||||||
|
nelmio_api_doc: ~
|
||||||
|
|
||||||
|
The **NelmioApiDocBundle** requires Twig as a template engine so do not forget
|
||||||
|
to enable it:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
# app/config/config.yml
|
||||||
|
framework:
|
||||||
|
templating:
|
||||||
|
engines: ['twig']
|
||||||
|
|
||||||
|
Usage
|
||||||
|
-----
|
||||||
|
|
||||||
|
The main problem with documentation is to keep it up to date. That's why the
|
||||||
|
**NelmioApiDocBundle** uses introspection a lot. Thanks to an annotation, it's
|
||||||
|
really easy to document an API method. The following chapters will help you
|
||||||
|
setup your API documentation:
|
||||||
|
|
||||||
|
* the-apidoc-annotation
|
||||||
|
* multiple-api-doc
|
||||||
|
* other-bundle-annotations
|
||||||
|
* swagger-support
|
||||||
|
* dunglasapibundle
|
||||||
|
* sandbox
|
||||||
|
* commands
|
||||||
|
|
||||||
|
Web Interface
|
||||||
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
You can browse the whole documentation at: ``http://example.org/api/doc``.
|
||||||
|
|
||||||
|
.. image:: webview.png
|
||||||
|
:align: center
|
||||||
|
|
||||||
|
.. image:: webview2.png
|
||||||
|
:align: center
|
||||||
|
|
||||||
|
On-The-Fly Documentation
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
By calling an URL with the parameter ``?_doc=1``, you will get the corresponding
|
||||||
|
documentation if available.
|
||||||
|
|
||||||
|
.. _`installation chapter`: https://getcomposer.org/doc/00-intro.md
|
||||||
@ -1,21 +1,16 @@
|
|||||||
Multiple API Documentation ("Views")
|
Multiple API Documentation ("Views")
|
||||||
------------------------------------
|
====================================
|
||||||
|
|
||||||
* [Accessing Specific API Views](#accessing-specific-api-views)
|
With the ``views`` tag in the ``@ApiDoc`` annotation, it is possible to create
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
With the `views` tag in the `@ApiDoc` annotation, it is possible to create
|
|
||||||
different views of your API documentation. Without the tag, all methods are
|
different views of your API documentation. Without the tag, all methods are
|
||||||
located in the `default` view, and can be found under the normal API
|
located in the ``default`` view, and can be found under the normal API
|
||||||
documentation url.
|
documentation url.
|
||||||
|
|
||||||
You can specify one or more _view_ names under which the method will be
|
You can specify one or more _view_ names under which the method will be
|
||||||
visible.
|
visible.
|
||||||
|
|
||||||
An example:
|
An example::
|
||||||
|
|
||||||
```php
|
|
||||||
/**
|
/**
|
||||||
* A resource
|
* A resource
|
||||||
*
|
*
|
||||||
@ -41,25 +36,24 @@ An example:
|
|||||||
public function getAnotherAction()
|
public function getAnotherAction()
|
||||||
{
|
{
|
||||||
}
|
}
|
||||||
```
|
|
||||||
|
|
||||||
In this case, only the first resource will be available under the default view,
|
In this case, only the first resource will be available under the default view,
|
||||||
while both methods will be available under the `premium` view.
|
while both methods will be available under the ``premium`` view.
|
||||||
|
|
||||||
|
Accessing Specific API Views
|
||||||
|
----------------------------
|
||||||
|
|
||||||
#### Accessing Specific API Views
|
The ``default`` view can be found at the normal location. Other views can be
|
||||||
|
found at ``http://your.documentation/<view name>``.
|
||||||
The `default` view can be found at the normal location. Other views can be
|
|
||||||
found at `http://your.documentation/<view name>`.
|
|
||||||
|
|
||||||
For instance, if your documentation is located at:
|
For instance, if your documentation is located at:
|
||||||
|
|
||||||
|
.. code-block:: text
|
||||||
|
|
||||||
http://example.org/doc/api/v1/
|
http://example.org/doc/api/v1/
|
||||||
|
|
||||||
then the `premium` view will be located at:
|
then the ``premium`` view will be located at:
|
||||||
|
|
||||||
|
.. code-block:: text
|
||||||
|
|
||||||
http://example.org/doc/api/v1/premium
|
http://example.org/doc/api/v1/premium
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
[back to index](index.md)
|
|
||||||
90
Resources/doc/other-bundle-annotations.Rst
Normal file
90
Resources/doc/other-bundle-annotations.Rst
Normal file
@ -0,0 +1,90 @@
|
|||||||
|
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
|
||||||
|
* ``@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``:
|
||||||
|
|
||||||
|
.. 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
|
||||||
@ -1,104 +0,0 @@
|
|||||||
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)
|
|
||||||
@ -1,58 +0,0 @@
|
|||||||
Sandbox
|
|
||||||
-------
|
|
||||||
|
|
||||||
This bundle provides a sandbox mode in order to test API methods. You can
|
|
||||||
configure this sandbox using the following parameters:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# app/config/config.yml
|
|
||||||
nelmio_api_doc:
|
|
||||||
sandbox:
|
|
||||||
authentication: # default is `~` (`null`), if set, the sandbox automatically
|
|
||||||
# send authenticated requests using the configured `delivery`
|
|
||||||
|
|
||||||
name: access_token # access token name or query parameter name or header name
|
|
||||||
|
|
||||||
delivery: http # `query`, `http`, and `header` are supported
|
|
||||||
|
|
||||||
# Required if http delivery is selected.
|
|
||||||
type: basic # `basic`, `bearer` are supported
|
|
||||||
|
|
||||||
custom_endpoint: true # default is `false`, if `true`, your user will be able to
|
|
||||||
# specify its own endpoint
|
|
||||||
|
|
||||||
enabled: true # default is `true`, you can set this parameter to `false`
|
|
||||||
# to disable the sandbox
|
|
||||||
|
|
||||||
endpoint: http://sandbox.example.com/ # default is `/app_dev.php`, use this parameter
|
|
||||||
# to define which URL to call through the sandbox
|
|
||||||
|
|
||||||
accept_type: application/json # default is `~` (`null`), if set, the value is
|
|
||||||
# automatically populated as the `Accept` header
|
|
||||||
|
|
||||||
body_format:
|
|
||||||
formats: [ form, json ] # array of enabled body formats,
|
|
||||||
# remove all elements to disable the selectbox
|
|
||||||
default_format: form # default is `form`, determines whether to send
|
|
||||||
# `x-www-form-urlencoded` data or json-encoded
|
|
||||||
# data (by setting this parameter to `json`) in
|
|
||||||
# sandbox requests
|
|
||||||
|
|
||||||
request_format:
|
|
||||||
formats: # default is `json` and `xml`,
|
|
||||||
json: application/json # override to add custom formats or disable
|
|
||||||
xml: application/xml # the default formats
|
|
||||||
|
|
||||||
method: format_param # default is `format_param`, alternately `accept_header`,
|
|
||||||
# decides how to request the response format
|
|
||||||
|
|
||||||
default_format: json # default is `json`,
|
|
||||||
# default content format to request (see formats)
|
|
||||||
|
|
||||||
entity_to_choice: false # default is `true`, if `false`, entity collection
|
|
||||||
# will not be mapped as choice
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
[back to index](index.md)
|
|
||||||
54
Resources/doc/sandbox.rst
Normal file
54
Resources/doc/sandbox.rst
Normal file
@ -0,0 +1,54 @@
|
|||||||
|
Sandbox
|
||||||
|
=======
|
||||||
|
|
||||||
|
This bundle provides a sandbox mode in order to test API methods. You can
|
||||||
|
configure this sandbox using the following parameters:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
# app/config/config.yml
|
||||||
|
nelmio_api_doc:
|
||||||
|
sandbox:
|
||||||
|
authentication: # default is `~` (`null`), if set, the sandbox automatically
|
||||||
|
# send authenticated requests using the configured `delivery`
|
||||||
|
|
||||||
|
name: access_token # access token name or query parameter name or header name
|
||||||
|
|
||||||
|
delivery: http # `query`, `http`, and `header` are supported
|
||||||
|
|
||||||
|
# Required if http delivery is selected.
|
||||||
|
type: basic # `basic`, `bearer` are supported
|
||||||
|
|
||||||
|
custom_endpoint: true # default is `false`, if `true`, your user will be able to
|
||||||
|
# specify its own endpoint
|
||||||
|
|
||||||
|
enabled: true # default is `true`, you can set this parameter to `false`
|
||||||
|
# to disable the sandbox
|
||||||
|
|
||||||
|
endpoint: http://sandbox.example.com/ # default is `/app_dev.php`, use this parameter
|
||||||
|
# to define which URL to call through the sandbox
|
||||||
|
|
||||||
|
accept_type: application/json # default is `~` (`null`), if set, the value is
|
||||||
|
# automatically populated as the `Accept` header
|
||||||
|
|
||||||
|
body_format:
|
||||||
|
formats: [ form, json ] # array of enabled body formats,
|
||||||
|
# remove all elements to disable the selectbox
|
||||||
|
default_format: form # default is `form`, determines whether to send
|
||||||
|
# `x-www-form-urlencoded` data or json-encoded
|
||||||
|
# data (by setting this parameter to `json`) in
|
||||||
|
# sandbox requests
|
||||||
|
|
||||||
|
request_format:
|
||||||
|
formats: # default is `json` and `xml`,
|
||||||
|
json: application/json # override to add custom formats or disable
|
||||||
|
xml: application/xml # the default formats
|
||||||
|
|
||||||
|
method: format_param # default is `format_param`, alternately `accept_header`,
|
||||||
|
# decides how to request the response format
|
||||||
|
|
||||||
|
default_format: json # default is `json`,
|
||||||
|
# default content format to request (see formats)
|
||||||
|
|
||||||
|
entity_to_choice: false # default is `true`, if `false`, entity collection
|
||||||
|
# will not be mapped as choice
|
||||||
@ -1,163 +0,0 @@
|
|||||||
Swagger Support
|
|
||||||
---------------
|
|
||||||
|
|
||||||
It is possible to make your application produce Swagger-compliant JSON output
|
|
||||||
based on `@ApiDoc` annotations, which can be used for consumption by
|
|
||||||
[swagger-ui](https://github.com/wordnik/swagger-ui).
|
|
||||||
|
|
||||||
### Annotation options
|
|
||||||
|
|
||||||
A couple of properties has been added to `@ApiDoc`:
|
|
||||||
|
|
||||||
To define a __resource description__:
|
|
||||||
|
|
||||||
```php
|
|
||||||
<?php
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @ApiDoc(
|
|
||||||
* resource=true,
|
|
||||||
* resourceDescription="Operations on users.",
|
|
||||||
* description="Retrieve list of users."
|
|
||||||
* )
|
|
||||||
*/
|
|
||||||
public function listUsersAction()
|
|
||||||
{
|
|
||||||
/* Stuff */
|
|
||||||
}
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
The `resourceDescription` is distinct from `description` as it applies to the
|
|
||||||
whole resource group and not just the particular API endpoint.
|
|
||||||
|
|
||||||
#### Defining a form-type as a GET form
|
|
||||||
|
|
||||||
If you use forms to capture GET requests, you will have to specify the
|
|
||||||
`paramType` to `query` in the annotation:
|
|
||||||
|
|
||||||
```php
|
|
||||||
|
|
||||||
<?php
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @ApiDoc(
|
|
||||||
* input = {"class" = "Foo\ContentBundle\Form\SearchType", "paramType" = "query"},
|
|
||||||
* ...
|
|
||||||
* )
|
|
||||||
*/
|
|
||||||
|
|
||||||
public function searchAction(Request $request)
|
|
||||||
{
|
|
||||||
```
|
|
||||||
|
|
||||||
### Multiple response models
|
|
||||||
|
|
||||||
Swagger provides you the ability to specify alternate output models for
|
|
||||||
different status codes. Example, `200` would return your default resource object
|
|
||||||
in JSON form, but `400` may return a custom validation error list object. This
|
|
||||||
can be specified through the `responseMap` property:
|
|
||||||
|
|
||||||
```php
|
|
||||||
<?php
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @ApiDoc(
|
|
||||||
* description="Retrieve list of users.",
|
|
||||||
* statusCodes={
|
|
||||||
* 400 = "Validation failed."
|
|
||||||
* },
|
|
||||||
* responseMap={
|
|
||||||
* 200 = "FooBundle\Entity\User",
|
|
||||||
* 400 = {
|
|
||||||
* "class"="CommonBundle\Model\ValidationErrors",
|
|
||||||
* "parsers"={"Nelmio\ApiDocBundle\Parser\JmsMetadataParser"}
|
|
||||||
* }
|
|
||||||
* }
|
|
||||||
* )
|
|
||||||
*/
|
|
||||||
public function updateUserAction()
|
|
||||||
{
|
|
||||||
/* Stuff */
|
|
||||||
}
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
This will tell Swagger that `CommonBundle\Model\ValidationErrors` is returned when this endpoint returns a `400 Validation failed.` HTTP response.
|
|
||||||
|
|
||||||
__Note:__ You can omit the `200` entry in the `responseMap` property and specify the default `output` property instead. That will result on the same thing.
|
|
||||||
|
|
||||||
### Integration with `wordnik/swagger-ui`
|
|
||||||
|
|
||||||
You could import the routes for use with [`swagger-ui`](https://github.com/wordnik/swagger-ui):
|
|
||||||
|
|
||||||
```yml
|
|
||||||
#app/config/routing.yml
|
|
||||||
|
|
||||||
nelmio_api_swagger:
|
|
||||||
resource: "@NelmioApiDocBundle/Resources/config/swagger_routing.yml"
|
|
||||||
prefix: /api-docs
|
|
||||||
```
|
|
||||||
|
|
||||||
Et voila!, simply specify http://yourdomain.com/api-docs in your `swagger-ui` instance and you are good to go.
|
|
||||||
|
|
||||||
__Note__: If your `swagger-ui` instance does not live under the same domain, you
|
|
||||||
will probably encounter some problems related to same-origin policy violations.
|
|
||||||
[NelmioCorsBundle](https://github.com/nelmio/NelmioCorsBundle) can solve this
|
|
||||||
problem for you. Read through how to allow cross-site requests for the
|
|
||||||
`/api-docs/*` pages.
|
|
||||||
|
|
||||||
### Dumping the Swagger-compliant JSON API definitions
|
|
||||||
|
|
||||||
To display all JSON definitions:
|
|
||||||
|
|
||||||
```
|
|
||||||
php app/console api:swagger:dump
|
|
||||||
```
|
|
||||||
|
|
||||||
To dump just the resource list:
|
|
||||||
|
|
||||||
```
|
|
||||||
php app/console api:swagger:dump --list-only
|
|
||||||
```
|
|
||||||
|
|
||||||
To dump just the API definition the `users` resource:
|
|
||||||
|
|
||||||
```
|
|
||||||
php app/console api:swagger:dump --resource=users
|
|
||||||
```
|
|
||||||
|
|
||||||
Specify the `--pretty` flag to display a prettified JSON output.
|
|
||||||
|
|
||||||
#### Dump to files
|
|
||||||
|
|
||||||
You can specify the destination if you wish to dump the JSON definition to a file:
|
|
||||||
|
|
||||||
```
|
|
||||||
php app/console api:swagger:dump --list-only swagger-docs/api-docs.json
|
|
||||||
php app/console api:swagger:dump --resource=users swagger-docs/users.json
|
|
||||||
```
|
|
||||||
|
|
||||||
Or, you can dump everything into a directory in one command:
|
|
||||||
|
|
||||||
```
|
|
||||||
php app/console api:swagger:dump swagger-docs
|
|
||||||
```
|
|
||||||
|
|
||||||
### Model naming
|
|
||||||
|
|
||||||
By default, the model naming strategy used is the `dot_notation` strategy. The
|
|
||||||
model IDs are simply the Fully Qualified Class Name (FQCN) of the class
|
|
||||||
associated to it, with the `\` replaced with `.`:
|
|
||||||
|
|
||||||
`Vendor\UserBundle\Entity\User => Vendor.UserBundle.Entity.User`
|
|
||||||
|
|
||||||
You can also change the `model_naming_strategy` in the configuration to
|
|
||||||
`last_segment_only`, if you want model IDs to be just the class name minus the
|
|
||||||
namespaces (`Vendor\UserBundle\Entity\User => User`). This will not afford you
|
|
||||||
the guarantee that model IDs are unique, but that would really just depend on
|
|
||||||
the classes you have in use.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
[back to index](index.md)
|
|
||||||
161
Resources/doc/swagger-support.rst
Normal file
161
Resources/doc/swagger-support.rst
Normal file
@ -0,0 +1,161 @@
|
|||||||
|
Swagger Support
|
||||||
|
===============
|
||||||
|
|
||||||
|
It is possible to make your application produce Swagger-compliant JSON output
|
||||||
|
based on ``@ApiDoc`` annotations, which can be used for consumption by
|
||||||
|
`swagger-ui`_.
|
||||||
|
|
||||||
|
Annotation options
|
||||||
|
------------------
|
||||||
|
|
||||||
|
A couple of properties has been added to ``@ApiDoc``:
|
||||||
|
|
||||||
|
To define a **resource description*::
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @ApiDoc(
|
||||||
|
* resource=true,
|
||||||
|
* resourceDescription="Operations on users.",
|
||||||
|
* description="Retrieve list of users."
|
||||||
|
* )
|
||||||
|
*/
|
||||||
|
public function listUsersAction()
|
||||||
|
{
|
||||||
|
/* Stuff */
|
||||||
|
}
|
||||||
|
|
||||||
|
The ``resourceDescription`` is distinct from ``description`` as it applies to the
|
||||||
|
whole resource group and not just the particular API endpoint.
|
||||||
|
|
||||||
|
Defining a form-type as a GET form
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
If you use forms to capture GET requests, you will have to specify the
|
||||||
|
``paramType`` to ``query`` in the annotation::
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @ApiDoc(
|
||||||
|
* input = {"class" = "Foo\ContentBundle\Form\SearchType", "paramType" = "query"},
|
||||||
|
* ...
|
||||||
|
* )
|
||||||
|
*/
|
||||||
|
|
||||||
|
public function searchAction(Request $request)
|
||||||
|
{
|
||||||
|
|
||||||
|
Multiple response models
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
Swagger provides you the ability to specify alternate output models for
|
||||||
|
different status codes. Example, ``200`` would return your default resource object
|
||||||
|
in JSON form, but ``400`` may return a custom validation error list object. This
|
||||||
|
can be specified through the ``responseMap`` property::
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @ApiDoc(
|
||||||
|
* description="Retrieve list of users.",
|
||||||
|
* statusCodes={
|
||||||
|
* 400 = "Validation failed."
|
||||||
|
* },
|
||||||
|
* responseMap={
|
||||||
|
* 200 = "FooBundle\Entity\User",
|
||||||
|
* 400 = {
|
||||||
|
* "class"="CommonBundle\Model\ValidationErrors",
|
||||||
|
* "parsers"={"Nelmio\ApiDocBundle\Parser\JmsMetadataParser"}
|
||||||
|
* }
|
||||||
|
* }
|
||||||
|
* )
|
||||||
|
*/
|
||||||
|
public function updateUserAction()
|
||||||
|
{
|
||||||
|
/* Stuff */
|
||||||
|
}
|
||||||
|
|
||||||
|
This will tell Swagger that ``CommonBundle\Model\ValidationErrors`` is returned
|
||||||
|
when this endpoint returns a ``400 Validation failed.`` HTTP response.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
You can omit the ``200`` entry in the ``responseMap`` property and specify
|
||||||
|
the default ``output`` property instead. That will result on the same thing.
|
||||||
|
|
||||||
|
Integration with ``wordnik/swagger-ui``
|
||||||
|
---------------------------------------
|
||||||
|
|
||||||
|
You could import the routes for use with `swagger-ui`_.
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
#app/config/routing.yml
|
||||||
|
nelmio_api_swagger:
|
||||||
|
resource: "@NelmioApiDocBundle/Resources/config/swagger_routing.yml"
|
||||||
|
prefix: /api-docs
|
||||||
|
|
||||||
|
Et voila!, simply specify http://yourdomain.com/api-docs in your ``swagger-ui``
|
||||||
|
instance and you are good to go.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
If your ``swagger-ui`` instance does not live under the same domain, you
|
||||||
|
will probably encounter some problems related to same-origin policy
|
||||||
|
violations. `NelmioCorsBundle`_ can solve this problem for you. Read through
|
||||||
|
how to allow cross-site requests for the ``/api-docs/*`` pages.
|
||||||
|
|
||||||
|
Dumping the Swagger-compliant JSON API definitions
|
||||||
|
--------------------------------------------------
|
||||||
|
|
||||||
|
To display all JSON definitions:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
$ php app/console api:swagger:dump
|
||||||
|
|
||||||
|
To dump just the resource list:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
$ php app/console api:swagger:dump --list-only
|
||||||
|
|
||||||
|
To dump just the API definition the ``users`` resource:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
$ php app/console api:swagger:dump --resource=users
|
||||||
|
|
||||||
|
Specify the ``--pretty`` flag to display a prettified JSON output.
|
||||||
|
|
||||||
|
Dump to files
|
||||||
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
You can specify the destination if you wish to dump the JSON definition to a file:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
$ php app/console api:swagger:dump --list-only swagger-docs/api-docs.json
|
||||||
|
$ php app/console api:swagger:dump --resource=users swagger-docs/users.json
|
||||||
|
|
||||||
|
Or, you can dump everything into a directory in one command:
|
||||||
|
|
||||||
|
.. code-block:: bash
|
||||||
|
|
||||||
|
$ php app/console api:swagger:dump swagger-docs
|
||||||
|
|
||||||
|
Model naming
|
||||||
|
------------
|
||||||
|
|
||||||
|
By default, the model naming strategy used is the ``dot_notation`` strategy. The
|
||||||
|
model IDs are simply the Fully Qualified Class Name (FQCN) of the class
|
||||||
|
associated to it, with the ``\`` replaced with ``.``:
|
||||||
|
|
||||||
|
.. code-block:: text
|
||||||
|
|
||||||
|
Vendor\UserBundle\Entity\User => Vendor.UserBundle.Entity.User
|
||||||
|
|
||||||
|
You can also change the ``model_naming_strategy`` in the configuration to
|
||||||
|
``last_segment_only``, if you want model IDs to be just the class name minus the
|
||||||
|
namespaces (``Vendor\UserBundle\Entity\User => User``). This will not afford you
|
||||||
|
the guarantee that model IDs are unique, but that would really just depend on
|
||||||
|
the classes you have in use.
|
||||||
|
|
||||||
|
.. _`swagger-ui`: https://github.com/wordnik/swagger-ui
|
||||||
|
.. _`NelmioCorsBundle`: https://github.com/nelmio/NelmioCorsBundle
|
||||||
@ -1,177 +0,0 @@
|
|||||||
The `ApiDoc()` Annotation
|
|
||||||
-------------------------
|
|
||||||
|
|
||||||
The bundle provides an `ApiDoc()` annotation for your controllers:
|
|
||||||
|
|
||||||
```php
|
|
||||||
<?php
|
|
||||||
|
|
||||||
namespace Your\Namespace;
|
|
||||||
|
|
||||||
use Nelmio\ApiDocBundle\Annotation\ApiDoc;
|
|
||||||
|
|
||||||
class YourController extends Controller
|
|
||||||
{
|
|
||||||
/**
|
|
||||||
* This is the documentation description of your method, it will appear
|
|
||||||
* on a specific pane. It will read all the text until the first
|
|
||||||
* annotation.
|
|
||||||
*
|
|
||||||
* @ApiDoc(
|
|
||||||
* resource=true,
|
|
||||||
* description="This is a description of your API method",
|
|
||||||
* filters={
|
|
||||||
* {"name"="a-filter", "dataType"="integer"},
|
|
||||||
* {"name"="another-filter", "dataType"="string", "pattern"="(foo|bar) ASC|DESC"}
|
|
||||||
* }
|
|
||||||
* )
|
|
||||||
*/
|
|
||||||
public function getAction()
|
|
||||||
{
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @ApiDoc(
|
|
||||||
* description="Create a new Object",
|
|
||||||
* input="Your\Namespace\Form\Type\YourType",
|
|
||||||
* output="Your\Namespace\Class"
|
|
||||||
* )
|
|
||||||
*/
|
|
||||||
public function postAction()
|
|
||||||
{
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @ApiDoc(
|
|
||||||
* description="Returns a collection of Object",
|
|
||||||
* requirements={
|
|
||||||
* {
|
|
||||||
* "name"="limit",
|
|
||||||
* "dataType"="integer",
|
|
||||||
* "requirement"="\d+",
|
|
||||||
* "description"="how many objects to return"
|
|
||||||
* }
|
|
||||||
* },
|
|
||||||
* parameters={
|
|
||||||
* {"name"="categoryId", "dataType"="integer", "required"=true, "description"="category id"}
|
|
||||||
* }
|
|
||||||
* )
|
|
||||||
*/
|
|
||||||
public function cgetAction($limit)
|
|
||||||
{
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
The following properties are available:
|
|
||||||
|
|
||||||
* `section`: allow to group resources
|
|
||||||
|
|
||||||
* `resource`: whether the method describes a main resource or not (default: `false`);
|
|
||||||
|
|
||||||
* `description`: a description of the API method;
|
|
||||||
|
|
||||||
* `https`: whether the method described requires the https protocol (default: `false`);
|
|
||||||
|
|
||||||
* `deprecated`: allow to set method as deprecated (default: `false`);
|
|
||||||
|
|
||||||
* `tags`: allow to tag a method (e.g. `beta` or `in-development`). Either a single tag or an array of tags. Each tag can have an optional hex colorcode attached.
|
|
||||||
|
|
||||||
```php
|
|
||||||
<?php
|
|
||||||
|
|
||||||
class YourController
|
|
||||||
{
|
|
||||||
/**
|
|
||||||
* @ApiDoc(
|
|
||||||
* tags={
|
|
||||||
* "stable",
|
|
||||||
* "deprecated" = "#ff0000"
|
|
||||||
* }
|
|
||||||
* )
|
|
||||||
*/
|
|
||||||
public function myFunction()
|
|
||||||
{
|
|
||||||
// ...
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
* `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, classes with Validation component metadata and classes that implement JsonSerializable) 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 something else is not found"
|
|
||||||
* }
|
|
||||||
* }
|
|
||||||
* )
|
|
||||||
*/
|
|
||||||
public function myFunction()
|
|
||||||
{
|
|
||||||
// ...
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
* `views`: the view(s) under which this resource will be shown. Leave empty to
|
|
||||||
specify the default view. Either a single view, or an array of views.
|
|
||||||
|
|
||||||
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`, `path`, etc), so to get the best out of it you should
|
|
||||||
define strict methods requirements etc.
|
|
||||||
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
[back to index](index.md)
|
|
||||||
161
Resources/doc/the-apidoc-annotation.rst
Normal file
161
Resources/doc/the-apidoc-annotation.rst
Normal file
@ -0,0 +1,161 @@
|
|||||||
|
The ``ApiDoc()`` Annotation
|
||||||
|
===========================
|
||||||
|
|
||||||
|
The bundle provides an ``ApiDoc()`` annotation for your controllers::
|
||||||
|
|
||||||
|
namespace Your\Namespace;
|
||||||
|
|
||||||
|
use Nelmio\ApiDocBundle\Annotation\ApiDoc;
|
||||||
|
|
||||||
|
class YourController extends Controller
|
||||||
|
{
|
||||||
|
/**
|
||||||
|
* This is the documentation description of your method, it will appear
|
||||||
|
* on a specific pane. It will read all the text until the first
|
||||||
|
* annotation.
|
||||||
|
*
|
||||||
|
* @ApiDoc(
|
||||||
|
* resource=true,
|
||||||
|
* description="This is a description of your API method",
|
||||||
|
* filters={
|
||||||
|
* {"name"="a-filter", "dataType"="integer"},
|
||||||
|
* {"name"="another-filter", "dataType"="string", "pattern"="(foo|bar) ASC|DESC"}
|
||||||
|
* }
|
||||||
|
* )
|
||||||
|
*/
|
||||||
|
public function getAction()
|
||||||
|
{
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @ApiDoc(
|
||||||
|
* description="Create a new Object",
|
||||||
|
* input="Your\Namespace\Form\Type\YourType",
|
||||||
|
* output="Your\Namespace\Class"
|
||||||
|
* )
|
||||||
|
*/
|
||||||
|
public function postAction()
|
||||||
|
{
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @ApiDoc(
|
||||||
|
* description="Returns a collection of Object",
|
||||||
|
* requirements={
|
||||||
|
* {
|
||||||
|
* "name"="limit",
|
||||||
|
* "dataType"="integer",
|
||||||
|
* "requirement"="\d+",
|
||||||
|
* "description"="how many objects to return"
|
||||||
|
* }
|
||||||
|
* },
|
||||||
|
* parameters={
|
||||||
|
* {"name"="categoryId", "dataType"="integer", "required"=true, "description"="category id"}
|
||||||
|
* }
|
||||||
|
* )
|
||||||
|
*/
|
||||||
|
public function cgetAction($limit)
|
||||||
|
{
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
The following properties are available:
|
||||||
|
|
||||||
|
* ``section``: allow to group resources
|
||||||
|
* ``resource``: whether the method describes a main resource or not (default:
|
||||||
|
``false``);
|
||||||
|
* ``description``: a description of the API method;
|
||||||
|
* ``https``: whether the method described requires the https protocol (default:
|
||||||
|
``false``);
|
||||||
|
* ``deprecated``: allow to set method as deprecated (default: ``false``);
|
||||||
|
* ``tags``: allow to tag a method (e.g. ``beta`` or ``in-development``). Either
|
||||||
|
a single tag or an array of tags. Each tag can have an optional hex colorcode
|
||||||
|
attached.
|
||||||
|
|
||||||
|
.. code-block:: php
|
||||||
|
|
||||||
|
class YourController
|
||||||
|
{
|
||||||
|
/**
|
||||||
|
* @ApiDoc(
|
||||||
|
* tags={
|
||||||
|
* "stable",
|
||||||
|
* "deprecated" = "#ff0000"
|
||||||
|
* }
|
||||||
|
* )
|
||||||
|
*/
|
||||||
|
public function myFunction()
|
||||||
|
{
|
||||||
|
// ...
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
* ``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, classes with Validation
|
||||||
|
component metadata and classes that implement JsonSerializable) 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:
|
||||||
|
|
||||||
|
.. code-block:: 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 something else is not found"
|
||||||
|
* }
|
||||||
|
* }
|
||||||
|
* )
|
||||||
|
*/
|
||||||
|
public function myFunction()
|
||||||
|
{
|
||||||
|
// ...
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
* ``views``: the view(s) under which this resource will be shown. Leave empty to
|
||||||
|
specify the default view. Either a single view, or an array of views.
|
||||||
|
|
||||||
|
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::
|
||||||
|
|
||||||
|
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``, ``path``, etc), so to get the best out of it you should
|
||||||
|
define strict methods requirements etc.
|
||||||
Loading…
x
Reference in New Issue
Block a user