Nelmioapidocbundle: Several routes with different paths per action

[melihovv]

Hi
Thanks for the awesome bundle!
I have a question.
In my app I have some controllers, which have more than one route pointing to the same action.
For example, there was /api/v1/referral-code/inviter endpoint, which later was renamed to /api/v1/referral-program/inviter and became deprecated. Then I added /mobile-api/v1/referral-program/inviter, which has different security scheme.
Is it possible to describe several routes pointing to the same action using your bundle? How to do it correctly?
Currently I have the error

User Warning: Multiple definitions for @OA\Get()->path
Using: \Nelmio\ApiDocBundle\ApiDocGenerator->generate() in /Users/xxx/Projects/work/yyy/vendor/nelmio/api-doc-bundle/ApiDocGenerator.php on line 82
Skipping: \GetReferralProgramInviterWebController->__invoke() in /Users/xxx/Projects/work/yyy/src/Controller/Web/Premium/Api/V1/GetReferralProgramInviter/GetReferralProgramInviterWebController.php on line 82

    /**
     * @Route(path="/api/v1/referral-program/inviter", methods={"GET"})
     * @Route(path="/api/v1/referral-code/inviter", methods={"GET"})
     * @Route(path="/mobile-api/v1/referral-program/inviter", methods={"GET"})
     *
     * @OA\Get(
     *     path="/api/v1/referral-program/inviter",
     *     security={"cookie_jwt"},
     * )
     * @OA\Get(
     *     path="/api/v1/referral-code/inviter",
     *     security={"cookie_jwt"},
     *     deprecated=true
     * )
     * @OA\Get(
     *     path="/mobile-api/v1/referral-program/inviter",
     *     security={"bearer"},
     * )
     * @OA\Parameter(
     *     name="guest_id",
     *     in="cookie",
     *     required=true,
     * )
     * @OA\Response(response="200", description="Success", @Model(type=GetReferralProgramInviterWebResponse::class))
     * @OA\Response(response="400", ref="#/components/responses/client_errors_get_referral_program_inviter")
     * @OA\Response(response="401", ref="#/components/responses/unauthorized")
     * @OA\Response(response="403", ref="#/components/responses/allowed_only_for_student")
     * @OA\Tag(name="Referral Program")
     */
public function __invoke(Request $request)

[ovidiuj]

Hello,
I have the same problem. Have you found any solution to fix that error?

[melihovv]

Unfortunately, no

[GuilhemN]

Sorry for answering so lately, it seems that you are actually using two @Get annotations with path /api/v1/referral-program/inviter.
Isn't the second one supposed to be /mobile-api/v1/referral-program/inviter?

[melihovv]

No, the first one with path=/api/v1/referral-program/inviter and second one with path=/api/v1/referral-code/inviter

[GuilhemN]

Isn't the second one supposed to be /mobile-api/v1/referral-program/inviter?

ok I meant the third one

[melihovv]

Yes, you are right, sorry

[melihovv]

@GuilhemN but error is the same even after mistake was corrected

[GuilhemN]

I found the issue, it seems there was a regression in v4 and we are no longer checking whether the path is defined in manual operations. (See https://github.com/nelmio/NelmioApiDocBundle/blob/master/Describer/OpenApiPhpDescriber.php#L90)

I'll submit a fix soon, thanks for the report!

[GuilhemN]

Could you check whether https://github.com/nelmio/NelmioApiDocBundle/pull/1767 does correctly fix your issue please?

[melihovv]

@GuilhemN yeah, it works!
Thanks for your work! 👍

[melihovv]

@GuilhemN I have one more similar problem.
I get User Warning: Multiple definitions for @OA\\Post()->description\n Using: \\Nelmio\\ApiDocBundle\\ApiDocGenerator->generate() in the following listing.
Is it possible to make the same fix like in #1767 but for description?

     * @Route(path="/api/v1/talk/video/config", methods={"POST"})
     * @Route(path="/api/v1/lesson/get-video-config", methods={"POST"})
     * @Route(path="/mobile-api/v1/talk/get-video-config", methods={"POST"})
     * @OA\Post(
     *     summary="Get video config",
     *     description="Allowed only for talk participant",
     * )
     * @OA\Post(
     *     path="/api/v1/talk/video/config",
     *     security={{"cookie_jwt": {}}, {"cookie_session": {}}},
     * )
     * @OA\Post(
     *     path="/api/v1/lesson/get-video-config",
     *     security={{"cookie_jwt": {}}, {"cookie_session": {}}},
     *     deprecated=true,
     *     description="Allowed only for talk participant. Deprecated, use /api/v1/talk/video/config",
     * )
     * @OA\Post(
     *     path="/mobile-api/v1/talk/get-video-config",
     *     security={{"bearer": {}}},
     * )

[GuilhemN]

That wouldn't be as simple actually as we use the mergeProperties from the swaggerPhp which doesn't allow overriding values.

For the description we could say the latest definitions wins but it's less straightforward when you want to merge two responses/requests.

For your case you could use php docs which acts as a default description though:
```php
/**

• Some summary.
  *
• The description
  */

[melihovv]

Thanks for your help :)