diff --git a/Resources/doc/index.md b/Resources/doc/index.md index b747933..b090bc7 100644 --- a/Resources/doc/index.md +++ b/Resources/doc/index.md @@ -33,17 +33,17 @@ Register the bundle in `app/AppKernel.php`: } Import the routing definition in `routing.yml`: - - # app/config/routing.yml - NelmioApiDocBundle: - resource: "@NelmioApiDocBundle/Resources/config/routing.yml" - prefix: /api/doc - +```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`: - - # app/config/config.yml - nelmio_api_doc: ~ - +``` yaml +# app/config/config.yml +nelmio_api_doc: ~ +``` Usage ----- @@ -318,51 +318,51 @@ documentation if available. 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` - # 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 - name: access_token # access token name or query parameter name or header name + delivery: http # `query`, `http`, and `header` are supported - delivery: http # `query`, `http`, and `header` are supported + # Required if http delivery is selected. + type: basic # `basic`, `bearer` 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 - 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 - 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 - 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 - 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 - 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 - 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) + 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) +``` ### Command A command is provided in order to dump the documentation in `json`, `markdown`, or `html`. @@ -378,81 +378,101 @@ For example to generate a static version of your documentation you can use: 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. + +### Caching + +It is a good idea to enable the internal caching mechanism on production: + + # app/config/config.yml + nelmio_api_doc: + cache: + enabled: true Configuration In-Depth ---------------------- You can specify your own API name: - - # app/config/config.yml - nelmio_api_doc: - name: My API - +``` +# 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: + authentication: + delivery: header + name: X-Custom - # app/config/config.yml - nelmio_api_doc: - authentication: - delivery: header - name: X-Custom - - # app/config/config.yml - nelmio_api_doc: - authentication: - delivery: query - name: param - - # app/config/config.yml - nelmio_api_doc: - authentication: - delivery: http - type: basic # or bearer +# app/config/config.yml +nelmio_api_doc: + authentication: + delivery: query + name: param +# app/config/config.yml +nelmio_api_doc: + 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: - - # app/config/config.yml - nelmio_api_doc: - exclude_sections: ["privateapi", "testapi"] - +```yaml +# app/config/config.yml +nelmio_api_doc: + exclude_sections: ["privateapi", "testapi"] +``` 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: - - #app/config/config.yml - services: - mybundle.api_doc.extractor.custom_parser: - class: MyBundle\Parser\CustomDocParser - tags: - - { name: nelmio_api_doc.extractor.parser, priority: 2 } - +```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: - - #app/config/config.yml - nelmio_api_doc: - # ... - motd: - template: AcmeApiBundle::Components/motd.html.twig - +```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`: - # app/config/config.yml - services: - mybundle.api_doc.extractor.my_annotation_handler: - class: MyBundle\AnnotationHandler\MyAnnotationHandler - tags: - - { name: 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). - ### Reference Configuration ``` yaml @@ -491,4 +511,18 @@ nelmio_api_doc: # Required if http delivery is selected. type: ~ # One of "basic"; "bearer" custom_endpoint: false + 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/swagger-support.md b/Resources/doc/swagger-support.md index 702f4be..f5dae68 100644 --- a/Resources/doc/swagger-support.md +++ b/Resources/doc/swagger-support.md @@ -5,7 +5,7 @@ NelmioApiDocBundle 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). -###Annotations### +###Annotation options### A couple of properties has been added to `@ApiDoc`: @@ -30,6 +30,27 @@ 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. +#### Defining a form-type as a GET form + +If you use forms to capture GET requests, you will have to specify the `paramType` to `query` in the annotation: + +```php + + 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. ##Configuration reference @@ -124,6 +148,7 @@ nelmio_api_doc: swagger: api_base_path: /api swagger_version: 1.2 + model_naming_strategy: dot_notation api_version: 0.1 info: title: Symfony2