Black Friday 2022 Offers 30% discount in Symfony, Twig and Sylius certifications (offer ends in 4 days)

Areas

Edit this page

Areas

We've already seen that you can configure which routes are documented using nelmio_api_doc.areas:

1
2
3
4
5
nelmio_api_doc:
    areas:
        path_patterns: [ ^/api ]
        host_patterns: [ ^api\. ]
        name_patterns: [ ^api_v1 ]

But in fact, this config option is way more powerful and allows you to split your documentation in several parts.

Configuration

You can define areas which will each generates a different documentation:

1
2
3
4
5
6
7
8
9
10
11
12
nelmio_api_doc:
    areas:
        default:
            path_patterns: [ ^/api ]
            host_patterns: [ ^api\. ]
        internal:
            path_patterns: [ ^/internal ]
        commercial:
            path_patterns: [ ^/commercial ]
        store:
            # Includes routes with names containing 'store'
            name_patterns: [ store ]

Your main documentation is under the default area. It's the one shown when accessing /api/doc.

Then update your routing to be able to access your different documentations:

1
2
3
4
5
6
7
8
9
10
11
# app/config/routing.yaml
app.swagger_ui:
    path: /api/doc/{area}
    methods: GET
    defaults: { _controller: nelmio_api_doc.controller.swagger_ui, area: default }

# To expose them as JSON
#app.swagger.areas:
#    path: /api/doc/{area}.json
#    methods: GET
#    defaults: { _controller: nelmio_api_doc.controller.swagger }

That's all! You can now access /api/doc/internal, /api/doc/commercial and /api/doc/store.

Use annotations to filter documented routes in each area

You can use the `@Areas` annotation inside your controllers to define your routes' areas.

First, you need to define which areas will use the`@Areas` annotations to filter
the routes that should be documented:

1
2
3
4
5
6
nelmio_api_doc:
    areas:
        default:
            path_patterns: [ ^/api ]
        internal:
            with_annotation: true

Then add the annotation before your controller or action:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
use Nelmio\Annotations as Nelmio;

/**
 * @Nelmio\Areas({"internal"}) => All actions in this controller are documented under the 'internal' area
 */
class MyController
{
    /**
     * @Nelmio\Areas({"internal"}) => This action is documented under the 'internal' area
     */
    public function index()
    {
       ...
    }
}
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.