NelmioApiDocBundle/Resources/doc/configuration-in-depth.md

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)