RetailCRM-Mirror/NelmioApiDocBundle
1
0
Fork 0
mirror of https://github.com/retailcrm/NelmioApiDocBundle.git synced 2025-02-02 15:51:48 +03:00
Code Issues Projects Releases Wiki Activity

Refactor doc

Browse Source
This commit is contained in:
William Durand 2015-10-27 10:27:13 +01:00
parent d49ac45866
commit d25dd30453
No known key found for this signature in database
GPG Key ID: A509BCF1C1274F3B
11 changed files with 718 additions and 619 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
Resources/doc/commands.md Normal file
View File

@ -0,0 +1,21 @@
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)

141
Resources/doc/configuration-in-depth.md Normal file
View File

@ -0,0 +1,141 @@
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)

59
Resources/doc/configuration-reference.md Normal file
View File

@ -0,0 +1,59 @@
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)

25
Resources/doc/dunglasapibundle.md Normal file
View File

@ -0,0 +1,25 @@
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)

15
Resources/doc/faq.md Normal file
View File

@ -0,0 +1,15 @@
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)

613
Resources/doc/index.md
View File

@ -4,6 +4,19 @@ NelmioApiDocBundle
The **NelmioApiDocBundle** bundle allows you to generate a decent documentation The **NelmioApiDocBundle** bundle allows you to generate a decent documentation
for your APIs. 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 Installation
------------ ------------
@ -57,326 +70,16 @@ Usage
The main problem with documentation is to keep it up to date. That's why the 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 **NelmioApiDocBundle** uses introspection a lot. Thanks to an annotation, it's
really easy to document an API method. really easy to document an API method. The following chapters will help you
setup your API documentation:
### The ApiDoc() Annotation
* [The `ApiDoc()` Annotation](the-apidoc-annotation.md)
The bundle provides an `ApiDoc()` annotation for your controllers: * [Multiple API Documentation a.k.a. "Views"](multiple-api-doc.md)
* [Other Bundle Annotations](other-bundle-annotations.md)
```php * [Swagger Support](swagger-support.md)
<?php * [DunglasApiBundle Support](dunglasapibundle.md)
* [Sandbox](sandbox.md)
namespace Your\Namespace; * [Commands](commands.md)
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.
### Multiple API Documentation ("Views")
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
located in the `default` view, and can be found under the normal API
documentation url.
You can specify one or more _view_ names under which the method will be
visible.
An example:
```php
/**
* A resource
*
* @ApiDoc(
* resource=true,
* description="This is a description of your API method",
* views = { "default", "premium" }
* )
*/
public function getAction()
{
}
/**
* Another resource
*
* @ApiDoc(
* resource=true,
* description="This is a description of another API method",
* views = { "premium" }
* )
*/
public function getAnotherAction()
{
}
```
In this case, only the first resource will be available under the default view,
while both methods will be available under the `premium` view.
#### 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>`.
For instance, if your documentation is located at:
http://example.org/doc/api/v1/
then the `premium` view will be located at:
http://example.org/doc/api/v1/premium
### 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 `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"},
}
```
#### Used 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.
### Web Interface ### Web Interface
@ -390,273 +93,3 @@ You can browse the whole documentation at: `http://example.org/api/doc`.
By calling an URL with the parameter `?_doc=1`, you will get the corresponding By calling an URL with the parameter `?_doc=1`, you will get the corresponding
documentation if available. documentation if available.
### 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
```
### Command
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.
### Swagger support
Read the [documentation for Swagger integration](https://github.com/nelmio/NelmioApiDocBundle/blob/master/Resources/doc/swagger-support.md)
for the necessary steps to make a Swagger-compliant documentation for your API.
### DunglasApiBundle support
This bundle recognizes and documents resources exposed with [DunglasApiBundle](https://github.com/dunglas/DunglasApiBundle).
Just install NelmioApiDoc 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"
```
### 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
```
Configuration In-Depth
----------------------
You can specify your own API name:
```yaml
# app/config/config.yml
nelmio_api_doc:
name: My API
```
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`).
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.
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 }
```
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
```
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"
```
### 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).
### 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
```
### 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'
```

65
Resources/doc/multiple-api-doc.md Normal file
View File

@ -0,0 +1,65 @@
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
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
documentation url.
You can specify one or more _view_ names under which the method will be
visible.
An example:
```php
/**
* A resource
*
* @ApiDoc(
* resource=true,
* description="This is a description of your API method",
* views = { "default", "premium" }
* )
*/
public function getAction()
{
}
/**
* Another resource
*
* @ApiDoc(
* resource=true,
* description="This is a description of another API method",
* views = { "premium" }
* )
*/
public function getAnotherAction()
{
}
```
In this case, only the first resource will be available under the default view,
while both methods will be available under the `premium` view.
#### 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>`.
For instance, if your documentation is located at:
http://example.org/doc/api/v1/
then the `premium` view will be located at:
http://example.org/doc/api/v1/premium
---
[back to index](index.md)

104
Resources/doc/other-bundle-annotations.md Normal file
View File

@ -0,0 +1,104 @@
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)

58
Resources/doc/sandbox.md Normal file
View File

@ -0,0 +1,58 @@
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)

57
Resources/doc/swagger-support.md
View File

@ -1,11 +1,11 @@
NelmioApiDocBundle Swagger Support
=================== ---------------
##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).
It is now 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
###Annotation options###
A couple of properties has been added to `@ApiDoc`: A couple of properties has been added to `@ApiDoc`:
@ -28,11 +28,13 @@ To define a __resource description__:
``` ```
The `resourceDescription` is distinct from `description` as it applies to the whole resource group and not just the particular API endpoint. 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 #### 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: If you use forms to capture GET requests, you will have to specify the
`paramType` to `query` in the annotation:
```php ```php
@ -51,7 +53,10 @@ If you use forms to capture GET requests, you will have to specify the `paramTyp
### Multiple response models ### 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: 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
<?php <?php
@ -96,7 +101,11 @@ nelmio_api_swagger:
Et voila!, simply specify http://yourdomain.com/api-docs in your `swagger-ui` instance and you are good to go. 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. __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 ### Dumping the Swagger-compliant JSON API definitions
@ -137,26 +146,18 @@ php app/console api:swagger:dump swagger-docs
### Model naming ### 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 `.`: 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` `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. 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.
##Configuration reference ---
```yml [back to index](index.md)
nelmio_api_doc:
swagger:
api_base_path: /api
swagger_version: 1.2
model_naming_strategy: dot_notation
api_version: 0.1
info:
title: Symfony2
description: My awesome Symfony2 app!
TermsOfServiceUrl: ~
contact: ~
license: ~
licenseUrl: ~
```

177
Resources/doc/the-apidoc-annotation.md Normal file
View File

@ -0,0 +1,177 @@
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)