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

Updated the docs. Added sections on caching and Swagger support.

Browse Source
This commit is contained in:
Bez Hermoso 2014-07-31 10:18:25 -07:00 committed by Bez Hermoso
parent d6777b881b
commit 9b544ef535
2 changed files with 181 additions and 122 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`:
# 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'
```

81
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).
###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
<?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:
```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.
###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
#app/config/routing.yml
@ -75,47 +96,50 @@ nelmio_api_swagger:
Et voila!, simply specify http://yourdomain.com/api-docs in your Swagger client and you are good to go.
###Dump Swagger-compliant JSON to file-system...
### Dumping the Swagger-compliant JSON API definitions
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:
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
@ -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