symfony nelmio apidoc bundle: areas for yaml-defined method (token refresh from gesdinet)

Question

While upgrading to php8.1 I had to upgrade several modules of my current project, including gesdinet's refresh-token. A ghost method was present in my controller so I could document this api with annotations but it's not possible anymore. I managed to define the refreshtoken api method in nelmio_api_doc.yaml so I can still use it and test it from my sandbox page.

The problem here is that I have 5 areas in my api's documentation (and so, 5 sandbox pages) but the refresh_token method appear in every single one of them instead of only one. I tried to insert various flavors and syntax of

areas:
    - front

in the configuration file but it doesn't seems to work.

Does anyone know how to restrict it the same way it was done with annotations but with the yaml file ? (nelmio's documentation is clearly lacking on the subject)

the "packages/nelmio_api_do.yaml" file

nelmio_api_doc:
    documentation:
        info:
            title: "API documentation"
            version: '%version%'
        sandbox:
            request_format:
                method: accept_header
            accept_type: application/json
            body_format:
                formats: [ form, json ]
                default_format: form
        paths:
            /api/front/token/refresh:
                post:
                    tags:
                        - Authentication
                    summary: Refresh token mechanism
                    parameters:
                        refresh_token:
                            in: formData
                            name: refresh_token
                            type: string
                    responses:
                        '200':
                            description: OK
                            schema:
                                type: object
                                properties:
                                    token:
                                        type: string
                                    refresh_token:
                                        type: string
                        '401':
                            description: An authentication exception occurred.
                    security: [ ]
    areas:
        default:
            path_patterns: [ ^/api/test/default ]
        front:
            path_patterns: [ ^/api/front ]

in advance thanks for your ideas. (php 8.1 / symfony 5.4 / nelmio 3.10.1)

Answer 1

This work for me

nelmio_api_doc:
    areas:
        oauth:
            path_patterns:
              - /oauth
            documentation:
                basePath: /
                info:
                    title: oauth api
                    description: oauth documentation
                paths:
                    /oauth/v2/token:
                        post:
                            tags:
                                - Authentication
                            produces:
                                - application/json
                            parameters:
                                -   name: client_id
                                    in: formData
                                    required: true
                                    type: string
                                -   name: username
                                    in: formData
                                    required: true
                                    type: string
                                    example: 'test@test.fr'
                                -   name: password
                                    in: formData
                                    required: true
                                    type: string
                                    example: 'password'
                                -   name: grant_type
                                    in: formData
                                    required: true
                                    type: string
                                    example: 'password'
                            responses:
                                200:
                                    description: Login successful
                                    schema:
                                        type: object
                                        properties:
                                            access_token:
                                                type: string
                                            expires_in:
                                                type: integer
                                            token_type:
                                                type: string
                                                example: 'bearer'
                                            scope:
                                                type: string
                                                example: null
                                            refresh_token:
                                                type: string
                                403:
                                    description: Login failed
                                    schema:
                                        type: array
                                        properties:
                                            error:
                                                type: string
                                            error_description:
                                                type: string
        default:
            path_patterns:
              - /address
            documentation:
                basePath: /
                info:
                    title: default API
                    description: default API documentation
                paths:
                    /address:
                        get:
                            tags:
                                - address
                            summary: OK - List address types
                            produces:
                                - application/json
                            parameters:
                                -   name: access_token
                                    type: string
                                    in: query
                                    required: true
                                    description: API access token
                            responses:
                                200:
                                    description: Returned when successful
                                    schema:
                                        items:
                                            $ref: "#definitions/AddressEntity"
                                        type: array
                                    examples:
                                        application/json:
                                            data:
                                                -   type:   adress type
                                                    id:     M
                                                    attributes:
                                                        id: M
                                                        label: Main Address
                                401:
                                    description: Bad access token

Answer 2

Nevermind guys, I eventually found the solution. I was trying to follow what I saw for defining paths in the yaml file but while I tried to insert it in

nelmio_api_doc->documentation->paths->[the_method_path] (which works)

the right way to do this and condition the method to an area is:

nelmio_api_doc->documentation->areas->[your_area_name]->paths->[the_method_path]

so now the file looks like:

nelmio_api_doc:
    documentation:
        info:
            title: "API documentation"
            version: '%version%'
        sandbox:
            request_format:
                method: accept_header
            accept_type: application/json
            body_format:
                formats: [ form, json ]
                default_format: form
        
    areas:
        default:
            path_patterns: [ ^/api/test/default ]
        front:
            path_patterns: [ ^/api/front ]
            paths:
                /api/front/token/refresh:
                    post:
                        tags:
                            - Authentication
                        summary: Refresh token mechanism
                        parameters:
                            refresh_token:
                                in: formData
                                name: refresh_token
                                type: string
                        responses:
                            '200':
                                description: OK
                                schema:
                                    type: object
                                    properties:
                                        token:
                                            type: string
                                        refresh_token:
                                            type: string
                            '401':
                                description: An authentication exception occurred.
                        security: [ ]