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
66
67
68
69
70
71
72
73
74
        # 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
    # Defines how to generate operation ids
    operation_id_generation: always_prepend
    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: []
        # https://docs.stoplight.io/docs/elements/b074dc47b2826-elements-configuration-options
        stoplight_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
            security:
                # Authentication schemes https://swagger.io/docs/specification/v3_0/authentication/
                MyBearerScheme:
                    type: 'http'
                    scheme: 'bearer'
            # 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.

use_validation_groups

type: boolean default: false

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

operation_id_generation

type: string or enum default: always_prepend

allowed values: always_prepend, conditionally_prepend, no_prepend or enum instance of Nelmio\ApiDocBundle\Describer\OperationIdGeneration

Defines how to generate operation ids. - always_prepend: Always prepend the HTTP method to the operation id. - conditionally_prepend: Checks if the operation id already starts with the HTTP method and prepends it if not. - no_prepend: Never prepends the HTTP method to the operation id. Warnings will be thrown if the operation id is not unique.

        1
2
3
        # config/packages/nelmio_api_doc.yaml
nelmio_api_doc:
    operation_id_generation: always_prepend
    

5.1

The operation_id_generation option was added in 5.1.

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, stoplight_config

UI configuration options.

        1
2
3
4
5
6
7
8
9
10
11
        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: []
        # https://docs.stoplight.io/docs/elements/b074dc47b2826-elements-configuration-options
        stoplight_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
28
29
30
31
        nelmio_api_doc:
    # ...

    areas:
        default:
            path_patterns:
                # Examples:
                # - ^/api
                # - '^/api(?!/admin)'
            host_patterns:
                # Example:
                # - ^api\.
            name_patterns:
                # Example:
                # - ^api_v1
            with_attribute: false
            security:
                MyBearerScheme:
                    type: 'http'
                    scheme: 'bearer'
            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_attribute

type: boolean default: false

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

security

type: dictionary default: []

Defines the security scheme(s) to use for the area. See authentication schemes for more information and possible values. See the security page for more information on how to configure security for your areas.

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

    areas:
        default:
            security:
                MyBearerScheme:
                    type: 'http'
                    scheme: 'bearer'
    

5.2

The possibility to automatically generate security definitions based on the #[IsGranted] attribute was added in version 5.2.

        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