RetailCRM-Mirror/NelmioApiDocBundle
1
0
Fork 0
mirror of https://github.com/retailcrm/NelmioApiDocBundle.git synced 2025-03-10 17:46:09 +03:00
Code Issues Projects Releases Wiki Activity

Improve documentation (authentication/sandbox)

Browse Source
This commit is contained in:
William DURAND 2014-01-10 11:16:09 +01:00
parent 6038fe842f
commit eca2eb6d80
2 changed files with 51 additions and 33 deletions
DependencyInjection
Configuration.php
Resources/doc
index.md

3
DependencyInjection/Configuration.php

@ -45,7 +45,7 @@ class Configuration implements ConfigurationInterface
->children()
->scalarNode('enabled')->defaultTrue()->end()
->scalarNode('endpoint')->defaultNull()->end()
->scalarNode('accept_type')->defaultValue('')->end()
->scalarNode('accept_type')->defaultNull()->end()
->enumNode('body_format')
->values(array('form', 'json'))
->defaultValue('form')
@ -69,7 +69,6 @@ class Configuration implements ConfigurationInterface
->scalarNode('delivery')
->isRequired()
->validate()
// header|query|request, but only query is implemented for now
->ifNotInArray(array('query', 'http_basic', 'header'))
->thenInvalid("Unknown authentication delivery type '%s'.")
->end()

81
Resources/doc/index.md

@ -257,8 +257,7 @@ input = {
}
```
=======
#### Used Parsers ####
#### 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
@ -279,13 +278,6 @@ generate returned data.
This feature also works for both the `input` and `output` properties.
### On-The-Fly Documentation
By calling an URL with the parameter `?_doc=1`, you will get the corresponding
documentation if available.
### Web Interface
You can browse the whole documentation at: `http://example.org/api/doc`.
@ -294,6 +286,48 @@ You can browse the whole documentation at: `http://example.org/api/doc`.
![](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.
### Sandbox
This bundle provides a sandbox mode in order to test API methods. You can
configure this sandbox using the following parameters:
# app/config/config.yml
nelmio_api_doc:
sandbox:
authentication: # default is `~` (`null`), if set, the value of the api
# key is read from the query string and appended to every
# sandbox api call.
name: access_token # access token name, or query parameter name, or header name
delivery: query # query, http_basic, and header 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: form # default is `form`, determines whether to send
# `x-www-form-urlencoded` data or json-encoded data
# in sandbox requests
request_format:
method: format_param # default format_param, alternately accept_header,
# decides how to request the response format
default_format: json # default json, alternately xml, determines which
# content format to request back by default
### Command
@ -310,6 +344,7 @@ 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.
Configuration In-Depth
----------------------
@ -319,26 +354,9 @@ You can specify your own API name:
nelmio_api_doc:
name: My API
This bundle provides a sandbox mode in order to test API methods. You can
configure this sandbox using the following parameters:
# app/config/config.yml
nelmio_api_doc:
sandbox:
authentication: # default null, if set, the value of the api key is read from the query string and appended to every sandbox api call
name: access_token
delivery: query # query or http_basic are supported
custom_endpoint: true # default false, if true, your user will be able to specify its own endpoint
enabled: true # default: true, you can set this parameter to `false` to disable the sandbox
endpoint: http://sandbox.example.com/ # default: /app_dev.php, use this parameter to define which URL to call through the sandbox
accept_type: application/json # default null, if set, the value is automatically populated as the Accept header
body_format: form # default form, determines whether to send x-www-form-urlencoded data or json-encoded data in sandbox requests
request_format:
method: format_param # default format_param, alternately accept_header, decides how to request the response format
default_format: json # default json, alternately xml, determines which content format to request back by default
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:
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:
@ -347,7 +365,8 @@ input is used, so you can configure their priorities via container tags. Here's
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:
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:
@ -384,7 +403,7 @@ nelmio_api_doc:
sandbox:
enabled: true
endpoint: ~
accept_type:
accept_type: ~
body_format: form
request_format:
method: format_param