Configuration Reference

The bundle configuration is stored under the nelmio_api_doc key in your application configuration.

        1
2
3
4
5
        # displays the default config values
$ php bin/console config:dump-reference nelmio_api_doc

# displays the actual config values used by your application
$ php bin/console debug:config nelmio_api_doc
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
        # Example default configuration
nelmio_api_doc:
    # Whether to use the symfony/type-info component for determining types.
    type_info: false
    # If true, `groups` passed to #[Model] attributes will be used to limit validation constraints
    use_validation_groups: false
    cache:
        # define cache pool to use
        pool: null
        # define cache item id
        item_id: null
    # The documentation to use as base
    documentation:
        # Example:
        # info:
        #   title: 'My App'
        #   description: 'My App Description'
     # List of enabled Media Types
    media_types:
        - json
    # UI configuration options
    html_config:
        assets_mode: cdn
        # https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
        swagger_ui_config: []
        # https://redocly.com/docs/redoc/config/
        redocly_config: []
    # Filter the routes that are documented
    areas:
        default:
            path_patterns:
                # Examples:
                # - ^/api
                # - '^/api(?!/admin)'
            host_patterns:
                # Example:
                # - ^api\.
            name_patterns:
                # Example:
                # - ^api_v1
        # whether to filter by attributes
        with_attribute: false
        # if set disables default routes without attributes
        disable_default_routes: false
        # The base documentation used for the area
        documentation:
            # Example:
            # info:
            #   title: 'My App'
            #   description: 'My App Description'
        cache:
            # define cache pool to use for the area
            pool: null
            # define cache item id for the area
            item_id: null
    models:
        use_jms: false
        names:
            -
                alias: ~ # Example: 'Foo'
                type: ~ # Example: 'App\Foo'
                groups: null
                options: null
                serializationContext: []
                areas: []
    

Configuration

type_info

type: boolean default: false

Whether to use symfony/type-info for determining types.

Tip

If you are using Symfony 7.2 or higher, you should set this option to true. As this greatly improves type detection.

4.35

Support for symfony/type-info was added in 4.35.

use_validation_groups

type: boolean default: false

If true, groups passed to #[Model] attributes will be used to limit validation constraints.

cache

type: dictionary allowed keys: pool, item_id

Cache configuration for the generated documentation.

        1
2
3
4
5
6
7
8
        nelmio_api_doc:
    # ...

    cache:
        # define cache pool to use
        pool: 'cache.app'
        # define cache item id
        item_id: 'nelmio_api_doc_cache'
    

documentation

type: dictionary

The api documentation to use as base.

        1
2
3
4
5
6
7
8
        nelmio_api_doc:
    # ...

    documentation:
        # Any valid OpenAPI/Swagger documentation
        info:
            title: 'My App'
            description: 'My App Description'
    

media_types

type: list default: ['json'] allowed values: json, xml

List of enabled Media Types.

html_config

type: dictionary default: [] allowed keys: assets_mode, swagger_ui_config, redocly_config

UI configuration options.

        1
2
3
4
5
6
7
8
9
        nelmio_api_doc:
    # ...

    html_config:
        assets_mode: 'cdn'
        # https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
        swagger_ui_config: []
        # https://redocly.com/docs/redoc/config/
        redocly_config: []
    

areas

type: dictionary

Filter the routes that are documented.

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
        nelmio_api_doc:
    # ...

    areas:
        default:
            path_patterns:
                # Examples:
                # - ^/api
                # - '^/api(?!/admin)'
            host_patterns:
                # Example:
                # - ^api\.
            name_patterns:
                # Example:
                # - ^api_v1
        with_attribute: false
        disable_default_routes: false
        documentation:
            # Example:
            # info:
            #   title: 'My App'
            #   description: 'My App Description'
        cache:
            # define cache pool to use for the area
            pool: null
            # define cache item id for the area
            item_id: null
    

path_patterns

type: list default: []

List of regular expressions to match against the path of the route.

host_patterns

type: list default: []

List of regular expressions to match against the host of the route.

name_patterns

type: list default: []

List of regular expressions to match against the name of the route.

with_annotation

type: boolean default: false

Whether to only document routes with the #[Areas] annotation/attribute.

4.36

with_annotation was deprecated in 4.36. Use with_attribute instead.

with_attribute

type: boolean default: false

Whether to only document routes with the #[Areas] annotation/attribute.

disable_default_routes

type: boolean default: false

If set, disables default routes without annotations/attributes.

documentation

type: dictionary default: []

The base documentation used for the area.

cache

type: dictionary allowed keys: pool, item_id

Cache configuration for the generated area documentation.

models

type: dictionary

Configuration for models.

use_jms

type: boolean default: false

Whether to use JMS Serializer for serialization.

names

type: list

List of models, this can be used to: - Define models that are not automatically detected. - Create a custom alias (schema name) for a model. (based groups/options/serializationContext/areas)

        1
2
3
4
5
6
7
8
9
10
11
12
        nelmio_api_doc:
    # ...

    models:
        use_jms: false
        names:
            -
                # Alias the class 'App\Foo' to 'FooPrivate' for the 'private' group
                alias: 'FooPrivate'
                type: 'App\Foo'
                groups:
                    - 'private'
    

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.

TOC

Version