How to reference response schema from file in NelmioApiDocBundle v3

[meridius]

The old NelmioApiDocBundle v2 could read the response schema from file when you just provided the file name to API method PHPDoc like this:

    /**
     * {
     *      "text":"Json Schema for Valid Response",
     *      "schema":"basket.json"
     * }
     */
    public function myApiMethod() {}

I know that you can define the schema in new v3 like this:

    /**
     * @Operation(
     *     tags={"Checkout - Basket"},
     *     summary="Returns requested Basket",
     *     @SWG\Response(
     *         response="200",
     *         description="Returned when successful",
     *         @SWG\Schema(ref="#definitions/checkout_basket"),
     *     ),
     * )
     */

and define the reference in the Nelmio bundle config like this:

nelmio_api_doc:
    documentation:
        definitions:
            checkout_basket:
                type: object
                properties:
                    success:
                        type: boolean
                        example: false
                    error:
                        type: string
                        example: message

So I tried it with file, but I can't figure out what the right path to the JSON should look like.

nelmio_api_doc:
    documentation:
        definitions:
            checkout_basket:
                type: file
                ref: ../../../src/validator/basket.json

[GuilhemN]

It is relative to /api/ (it won't be inlined by the bundle so it has to be in your web folder), so I guess in your case something like ../validator/basket.json.

Btw no need for type: file and ref does not exist, it's $ref.

[meridius]

I see now. It was working before because we have a custom service implementing HandlerInterface and tagged as nelmio_api_doc.extractor.handler.
Is there a way to get it working again? Because it seems that there is no support for this feature in 3.x anymore and I really liked how the JSON could be located in application sources and just "linked" this way to ApiDoc.

---

Also I wasn't able to get the reference working other than providing the whole URL to it when it is located in <app_dir>/web/basket.json:

nelmio_api_doc:
    areas:
        path_patterns:
            - ^/checkout/.*$
            - ^/store/.*$
            - ^/$
    documentation:
        info:
            title: app
            version: 1.0.0
        definitions:
            checkout_basket:
                $ref: http://localhost:8000/basket.json

I've read about basePath and tried to set it to documentation, but it doesn't help.
Every time the ApiDoc reports JS following error saying that basePath is undefined:

Resolver error at definitions.checkout_basket.$ref
Could not resolve reference because of: Tried to resolve a relative URL, without having a basePath. path: 'basket.json' basePath: 'undefined'

[GuilhemN]

Could you try providing host in your config please? (see https://github.com/nelmio/NelmioApiDocBundle/pull/1265/files#diff-fdd764ee72f777e180ace83412a44158R108)

[meridius]

Thank you, but that didn't help either. I still get the error mentioned before.

[GuilhemN]

I'm not sure but it seems to be a swagger-ui issue swagger-api/swagger-editor#1409. If it is I don't think we can fix it here unfortunately.

[meridius]

It seems to be. Thank you away.