From d25dd30453ac9948f41491a6ea367d28e464fac2 Mon Sep 17 00:00:00 2001
From: William Durand <will+git@drnd.me>
Date: Tue, 27 Oct 2015 10:27:13 +0100
Subject: [PATCH] Refactor doc
---
Resources/doc/commands.md | 21 +
Resources/doc/configuration-in-depth.md | 141 +++++
Resources/doc/configuration-reference.md | 59 +++
Resources/doc/dunglasapibundle.md | 25 +
Resources/doc/faq.md | 15 +
Resources/doc/index.md | 613 +---------------------
Resources/doc/multiple-api-doc.md | 65 +++
Resources/doc/other-bundle-annotations.md | 104 ++++
Resources/doc/sandbox.md | 58 ++
Resources/doc/swagger-support.md | 59 ++-
Resources/doc/the-apidoc-annotation.md | 177 +++++++
11 files changed, 718 insertions(+), 619 deletions(-)
create mode 100644 Resources/doc/commands.md
create mode 100644 Resources/doc/configuration-in-depth.md
create mode 100644 Resources/doc/configuration-reference.md
create mode 100644 Resources/doc/dunglasapibundle.md
create mode 100644 Resources/doc/faq.md
create mode 100644 Resources/doc/multiple-api-doc.md
create mode 100644 Resources/doc/other-bundle-annotations.md
create mode 100644 Resources/doc/sandbox.md
create mode 100644 Resources/doc/the-apidoc-annotation.md
diff --git a/Resources/doc/commands.md b/Resources/doc/commands.md
new file mode 100644
index 0000000..3e01109
--- /dev/null
+++ b/Resources/doc/commands.md
@@ -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)
diff --git a/Resources/doc/configuration-in-depth.md b/Resources/doc/configuration-in-depth.md
new file mode 100644
index 0000000..dfecdf9
--- /dev/null
+++ b/Resources/doc/configuration-in-depth.md
@@ -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)
diff --git a/Resources/doc/configuration-reference.md b/Resources/doc/configuration-reference.md
new file mode 100644
index 0000000..bad19b1
--- /dev/null
+++ b/Resources/doc/configuration-reference.md
@@ -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)
diff --git a/Resources/doc/dunglasapibundle.md b/Resources/doc/dunglasapibundle.md
new file mode 100644
index 0000000..46cdf2a
--- /dev/null
+++ b/Resources/doc/dunglasapibundle.md
@@ -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)
diff --git a/Resources/doc/faq.md b/Resources/doc/faq.md
new file mode 100644
index 0000000..467e699
--- /dev/null
+++ b/Resources/doc/faq.md
@@ -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)
diff --git a/Resources/doc/index.md b/Resources/doc/index.md
index e1c9854..8249698 100644
--- a/Resources/doc/index.md
+++ b/Resources/doc/index.md
@@ -4,6 +4,19 @@ 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
------------
@@ -57,326 +70,16 @@ 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 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.
-
-### 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.
+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
@@ -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
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'
-```
diff --git a/Resources/doc/multiple-api-doc.md b/Resources/doc/multiple-api-doc.md
new file mode 100644
index 0000000..e56997f
--- /dev/null
+++ b/Resources/doc/multiple-api-doc.md
@@ -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)
diff --git a/Resources/doc/other-bundle-annotations.md b/Resources/doc/other-bundle-annotations.md
new file mode 100644
index 0000000..dcc5348
--- /dev/null
+++ b/Resources/doc/other-bundle-annotations.md
@@ -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)
diff --git a/Resources/doc/sandbox.md b/Resources/doc/sandbox.md
new file mode 100644
index 0000000..97909d4
--- /dev/null
+++ b/Resources/doc/sandbox.md
@@ -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)
diff --git a/Resources/doc/swagger-support.md b/Resources/doc/swagger-support.md
index 59d34b8..8868ba4 100644
--- a/Resources/doc/swagger-support.md
+++ b/Resources/doc/swagger-support.md
@@ -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`:
@@ -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
-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
@@ -44,14 +46,17 @@ If you use forms to capture GET requests, you will have to specify the `paramTyp
* ...
* )
*/
-
+
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:
+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
@@ -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.
-__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
@@ -137,26 +146,18 @@ 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 `.`:
+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.
+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
-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: ~
-```
+[back to index](index.md)
diff --git a/Resources/doc/the-apidoc-annotation.md b/Resources/doc/the-apidoc-annotation.md
new file mode 100644
index 0000000..f56f9a5
--- /dev/null
+++ b/Resources/doc/the-apidoc-annotation.md
@@ -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)