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

Merge pull request #456 from bezhermoso/swagger-doc

Browse Source 
Updated the docs. Added sections on caching and Swagger support.
This commit is contained in:
William Durand 2014-08-27 08:59:42 +02:00
commit 72a1418b7d
2 changed files with 184 additions and 123 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

222
Resources/doc/index.md
View File

@ -33,17 +33,17 @@ Register the bundle in `app/AppKernel.php`:
} }
Import the routing definition in `routing.yml`: Import the routing definition in `routing.yml`:
```yaml
# app/config/routing.yml # app/config/routing.yml
NelmioApiDocBundle: NelmioApiDocBundle:
resource: "@NelmioApiDocBundle/Resources/config/routing.yml" resource: "@NelmioApiDocBundle/Resources/config/routing.yml"
prefix: /api/doc prefix: /api/doc
```
Enable the bundle's configuration in `app/config/config.yml`: Enable the bundle's configuration in `app/config/config.yml`:
``` yaml
# app/config/config.yml # app/config/config.yml
nelmio_api_doc: ~ nelmio_api_doc: ~
```
Usage Usage
----- -----
@ -318,51 +318,51 @@ documentation if available.
This bundle provides a sandbox mode in order to test API methods. You can This bundle provides a sandbox mode in order to test API methods. You can
configure this sandbox using the following parameters: 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 name: access_token # access token name or query parameter name or header name
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
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. custom_endpoint: true # default is `false`, if `true`, your user will be able to
type: basic # `basic`, `bearer` are supported # specify its own endpoint
custom_endpoint: true # default is `false`, if `true`, your user will be able to enabled: true # default is `true`, you can set this parameter to `false`
# specify its own endpoint # to disable the sandbox
enabled: true # default is `true`, you can set this parameter to `false` endpoint: http://sandbox.example.com/ # default is `/app_dev.php`, use this parameter
# to disable the sandbox # to define which URL to call through the sandbox
endpoint: http://sandbox.example.com/ # default is `/app_dev.php`, use this parameter accept_type: application/json # default is `~` (`null`), if set, the value is
# to define which URL to call through the sandbox # automatically populated as the `Accept` header
accept_type: application/json # default is `~` (`null`), if set, the value is body_format:
# automatically populated as the `Accept` header 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: request_format:
formats: [ form, json ] # array of enabled body formats, formats: # default is `json` and `xml`,
# remove all elements to disable the selectbox json: application/json # override to add custom formats or disable
default_format: form # default is `form`, determines whether to send xml: application/xml # the default formats
# `x-www-form-urlencoded` data or json-encoded
# data (by setting this parameter to `json`) in
# sandbox requests
request_format: method: format_param # default is `format_param`, alternately `accept_header`,
formats: # default is `json` and `xml`, # decides how to request the response format
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)
default_format: json # default is `json`,
# default content format to request (see formats)
```
### Command ### Command
A command is provided in order to dump the documentation in `json`, `markdown`, or `html`. 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. 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. 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 Configuration In-Depth
---------------------- ----------------------
You can specify your own API name: You can specify your own API name:
```
# app/config/config.yml # app/config/config.yml
nelmio_api_doc: nelmio_api_doc:
name: My API name: My API
```
You can choose between different authentication methods: 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 # app/config/config.yml
nelmio_api_doc: nelmio_api_doc:
authentication: authentication:
delivery: header delivery: query
name: X-Custom name: param
# 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: http
type: basic # or bearer
```
When choosing an `http` delivery, `name` defaults to `Authorization`, 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`). 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: You can specify which sections to exclude from the documentation generation:
```yaml
# app/config/config.yml # app/config/config.yml
nelmio_api_doc: nelmio_api_doc:
exclude_sections: ["privateapi", "testapi"] exclude_sections: ["privateapi", "testapi"]
```
The bundle provides a way to register multiple `input` parsers. The first parser 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 that can handle the specified input is used, so you can configure their
priorities via container tags. Here's an example parser service registration: priorities via container tags. Here's an example parser service registration:
```yaml
#app/config/config.yml # app/config/config.yml
services: services:
mybundle.api_doc.extractor.custom_parser: mybundle.api_doc.extractor.custom_parser:
class: MyBundle\Parser\CustomDocParser class: MyBundle\Parser\CustomDocParser
tags: tags:
- { name: nelmio_api_doc.extractor.parser, priority: 2 } - { name: nelmio_api_doc.extractor.parser, priority: 2 }
```
You can also define your own motd content (above methods list). All you have to You can also define your own motd content (above methods list). All you have to
do is add to configuration: do is add to configuration:
```yaml
#app/config/config.yml # app/config/config.yml
nelmio_api_doc: nelmio_api_doc:
# ... # ...
motd: motd:
template: AcmeApiBundle::Components/motd.html.twig 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 ### Using Your Own Annotations
If you have developed your own project-related annotations, and you want to parse them to populate 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 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`: `Nelmio\ApiDocBundle\Extractor\HandlerInterface` and tag it as `nelmio_api_doc.extractor.handler`:
# app/config/config.yml ```yaml
services: # app/config/config.yml
mybundle.api_doc.extractor.my_annotation_handler: services:
class: MyBundle\AnnotationHandler\MyAnnotationHandler mybundle.api_doc.extractor.my_annotation_handler:
tags: class: MyBundle\AnnotationHandler\MyAnnotationHandler
- { name: nelmio_api_doc.extractor.handler } tags:
- { name: nelmio_api_doc.extractor.handler }
```
Look at the built-in [Handlers](https://github.com/nelmio/NelmioApiDocBundle/tree/master/Extractor/Handler). Look at the built-in [Handlers](https://github.com/nelmio/NelmioApiDocBundle/tree/master/Extractor/Handler).
### Reference Configuration ### Reference Configuration
``` yaml ``` yaml
@ -491,4 +511,18 @@ nelmio_api_doc:
# Required if http delivery is selected. # Required if http delivery is selected.
type: ~ # One of "basic"; "bearer" type: ~ # One of "basic"; "bearer"
custom_endpoint: false 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'
``` ```

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

@ -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). 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`: 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. 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
<?php
/**
* @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: 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
@ -61,9 +82,9 @@ This will tell Swagger that `CommonBundle\Model\ValidationErrors` is returned wh
__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. __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.
###wordnik/swagger-ui consumption... ### Integration with `wordnik/swagger-ui`
You could import the routes for Swagger integration: You could import the routes for use with [`swagger-ui`](https://github.com/wordnik/swagger-ui):
```yml ```yml
#app/config/routing.yml #app/config/routing.yml
@ -73,49 +94,54 @@ nelmio_api_swagger:
prefix: /api-docs prefix: /api-docs
``` ```
Et voila!, simply specify http://yourdomain.com/api-docs in your Swagger client and you are good to go. Et voila!, simply specify http://yourdomain.com/api-docs in your `swagger-ui` instance and you are good to go.
###Dump Swagger-compliant JSON to file-system... __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.
The routes registered with the method above will read your `@ApiDoc` annotation during every request. Naturally, this will be slow because the bundle will parse your annotations every single time. For improved performance, you might be better off dumping the JSON output to the file-system and let your web-server serve them directly. If you want that, execute this command: ### Dumping the Swagger-compliant JSON API definitions
To display all JSON definitions:
``` ```
php app/console api:swagger:dump app/Resources/swagger-docs php app/console api:swagger:dump
``` ```
The above command will dump JSON files under the `app/Resources/swagger-docs` directory (relative to your project root), and you can now process or server the files however you want. The destination defaults to the project root if not specified. To dump just the resource list:
####Selective dumps
Dump the `api-docs.json` resource list file only:
``` ```
php app/console api:swagger:dump --list-only api-docs.json php app/console api:swagger:dump --list-only
``` ```
Dump a specific resource API declaration only: To dump just the API definition the `users` resource:
``` ```
php app/console api:swagger:dump --resource=users users.json php app/console api:swagger:dump --resource=users
``` ```
The above command will dump the `/users` API declaration in an `users.json` file.
### Defining a form-type as a GET form Specify the `--pretty` flag to display a prettified JSON output.
If you use forms to capture GET requests, you will have to specify the `paramType` to `query` in the annotation: #### Dump to files
```php You can specify the destination if you wish to dump the JSON definition to a file:
<?php
/**
* @ApiDoc(
* input = {"class" = "Foo\ContentBundle\Form\SearchType", "paramType" = "query"},
* ...
* )
*/
public function searchAction(Request $request)
{
``` ```
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:
```
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 `.`:
`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.
##Configuration reference ##Configuration reference
@ -124,6 +150,7 @@ nelmio_api_doc:
swagger: swagger:
api_base_path: /api api_base_path: /api
swagger_version: 1.2 swagger_version: 1.2
model_naming_strategy: dot_notation
api_version: 0.1 api_version: 0.1
info: info:
title: Symfony2 title: Symfony2