From db5303fcd75d0d93ccf39403c54312bcc24cd92c Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 5 Mar 2016 19:46:43 +0100 Subject: [PATCH] Transformed all files --- Resources/doc/commands.md | 21 --- Resources/doc/commands.rst | 21 +++ Resources/doc/configuration-in-depth.md | 141 -------------- Resources/doc/configuration-in-depth.rst | 132 +++++++++++++ Resources/doc/configuration-reference.md | 59 ------ Resources/doc/configuration-reference.rst | 55 ++++++ Resources/doc/dunglasapibundle.md | 25 --- Resources/doc/dunglasapibundle.rst | 23 +++ Resources/doc/faq.md | 15 -- Resources/doc/faq.rst | 12 ++ Resources/doc/index.md | 95 ---------- Resources/doc/index.rst | 115 ++++++++++++ ...ltiple-api-doc.md => multiple-api-doc.rst} | 34 ++-- Resources/doc/other-bundle-annotations.Rst | 90 +++++++++ Resources/doc/other-bundle-annotations.md | 104 ---------- Resources/doc/sandbox.md | 58 ------ Resources/doc/sandbox.rst | 54 ++++++ Resources/doc/swagger-support.md | 163 ---------------- Resources/doc/swagger-support.rst | 161 ++++++++++++++++ Resources/doc/the-apidoc-annotation.md | 177 ------------------ Resources/doc/the-apidoc-annotation.rst | 161 ++++++++++++++++ 21 files changed, 838 insertions(+), 878 deletions(-) delete mode 100644 Resources/doc/commands.md create mode 100644 Resources/doc/commands.rst delete mode 100644 Resources/doc/configuration-in-depth.md create mode 100644 Resources/doc/configuration-in-depth.rst delete mode 100644 Resources/doc/configuration-reference.md create mode 100644 Resources/doc/configuration-reference.rst delete mode 100644 Resources/doc/dunglasapibundle.md create mode 100644 Resources/doc/dunglasapibundle.rst delete mode 100644 Resources/doc/faq.md create mode 100644 Resources/doc/faq.rst delete mode 100644 Resources/doc/index.md create mode 100644 Resources/doc/index.rst rename Resources/doc/{multiple-api-doc.md => multiple-api-doc.rst} (61%) create mode 100644 Resources/doc/other-bundle-annotations.Rst delete mode 100644 Resources/doc/other-bundle-annotations.md delete mode 100644 Resources/doc/sandbox.md create mode 100644 Resources/doc/sandbox.rst delete mode 100644 Resources/doc/swagger-support.md create mode 100644 Resources/doc/swagger-support.rst delete mode 100644 Resources/doc/the-apidoc-annotation.md create mode 100644 Resources/doc/the-apidoc-annotation.rst diff --git a/Resources/doc/commands.md b/Resources/doc/commands.md deleted file mode 100644 index 3e011093b..000000000 --- a/Resources/doc/commands.md +++ /dev/null @@ -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) diff --git a/Resources/doc/commands.rst b/Resources/doc/commands.rst new file mode 100644 index 000000000..99d402648 --- /dev/null +++ b/Resources/doc/commands.rst @@ -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. diff --git a/Resources/doc/configuration-in-depth.md b/Resources/doc/configuration-in-depth.md deleted file mode 100644 index dfecdf978..000000000 --- a/Resources/doc/configuration-in-depth.md +++ /dev/null @@ -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) diff --git a/Resources/doc/configuration-in-depth.rst b/Resources/doc/configuration-in-depth.rst new file mode 100644 index 000000000..cd80b688a --- /dev/null +++ b/Resources/doc/configuration-in-depth.rst @@ -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" diff --git a/Resources/doc/configuration-reference.md b/Resources/doc/configuration-reference.md deleted file mode 100644 index bad19b16e..000000000 --- a/Resources/doc/configuration-reference.md +++ /dev/null @@ -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) diff --git a/Resources/doc/configuration-reference.rst b/Resources/doc/configuration-reference.rst new file mode 100644 index 000000000..a4cbddb0a --- /dev/null +++ b/Resources/doc/configuration-reference.rst @@ -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' diff --git a/Resources/doc/dunglasapibundle.md b/Resources/doc/dunglasapibundle.md deleted file mode 100644 index 46cdf2aa3..000000000 --- a/Resources/doc/dunglasapibundle.md +++ /dev/null @@ -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) diff --git a/Resources/doc/dunglasapibundle.rst b/Resources/doc/dunglasapibundle.rst new file mode 100644 index 000000000..b2531b2fb --- /dev/null +++ b/Resources/doc/dunglasapibundle.rst @@ -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 diff --git a/Resources/doc/faq.md b/Resources/doc/faq.md deleted file mode 100644 index 467e6990f..000000000 --- a/Resources/doc/faq.md +++ /dev/null @@ -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) diff --git a/Resources/doc/faq.rst b/Resources/doc/faq.rst new file mode 100644 index 000000000..53c31bc2f --- /dev/null +++ b/Resources/doc/faq.rst @@ -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 diff --git a/Resources/doc/index.md b/Resources/doc/index.md deleted file mode 100644 index 824969829..000000000 --- a/Resources/doc/index.md +++ /dev/null @@ -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`. - -![](https://github.com/nelmio/NelmioApiDocBundle/raw/master/Resources/doc/webview.png) - -![](https://github.com/nelmio/NelmioApiDocBundle/raw/master/Resources/doc/webview2.png) - -### On-The-Fly Documentation - -By calling an URL with the parameter `?_doc=1`, you will get the corresponding -documentation if available. diff --git a/Resources/doc/index.rst b/Resources/doc/index.rst new file mode 100644 index 000000000..79f3faaf3 --- /dev/null +++ b/Resources/doc/index.rst @@ -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 + + `. +The ``default`` view can be found at the normal location. Other views can be +found at ``http://your.documentation/``. For instance, if your documentation is located at: - http://example.org/doc/api/v1/ +.. code-block:: text -then the `premium` view will be located at: + http://example.org/doc/api/v1/ - http://example.org/doc/api/v1/premium +then the ``premium`` view will be located at: ---- +.. code-block:: text -[back to index](index.md) + http://example.org/doc/api/v1/premium diff --git a/Resources/doc/other-bundle-annotations.Rst b/Resources/doc/other-bundle-annotations.Rst new file mode 100644 index 000000000..044781200 --- /dev/null +++ b/Resources/doc/other-bundle-annotations.Rst @@ -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 diff --git a/Resources/doc/other-bundle-annotations.md b/Resources/doc/other-bundle-annotations.md deleted file mode 100644 index dcc5348d5..000000000 --- a/Resources/doc/other-bundle-annotations.md +++ /dev/null @@ -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) diff --git a/Resources/doc/sandbox.md b/Resources/doc/sandbox.md deleted file mode 100644 index 97909d4c3..000000000 --- a/Resources/doc/sandbox.md +++ /dev/null @@ -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) diff --git a/Resources/doc/sandbox.rst b/Resources/doc/sandbox.rst new file mode 100644 index 000000000..20a47d32e --- /dev/null +++ b/Resources/doc/sandbox.rst @@ -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 diff --git a/Resources/doc/swagger-support.md b/Resources/doc/swagger-support.md deleted file mode 100644 index 8868ba42e..000000000 --- a/Resources/doc/swagger-support.md +++ /dev/null @@ -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 - 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) diff --git a/Resources/doc/swagger-support.rst b/Resources/doc/swagger-support.rst new file mode 100644 index 000000000..ed3e592e0 --- /dev/null +++ b/Resources/doc/swagger-support.rst @@ -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 diff --git a/Resources/doc/the-apidoc-annotation.md b/Resources/doc/the-apidoc-annotation.md deleted file mode 100644 index f56f9a55a..000000000 --- a/Resources/doc/the-apidoc-annotation.md +++ /dev/null @@ -1,177 +0,0 @@ -The `ApiDoc()` Annotation -------------------------- - -The bundle provides an `ApiDoc()` annotation for your controllers: - -```php -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) diff --git a/Resources/doc/the-apidoc-annotation.rst b/Resources/doc/the-apidoc-annotation.rst new file mode 100644 index 000000000..e4139b3c0 --- /dev/null +++ b/Resources/doc/the-apidoc-annotation.rst @@ -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.