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 -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/`. - -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/`. + +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 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 +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)