Two paths for same method

[zFly]

Hello,

I am trying to achieve something similiar to this stackoverflow question.

I tried this approach

/**
 * @SWG\Post(
 *   path="/user/login",
 *   @SWG\Response(response=200, description="OK")
 * )
 * @SWG\Path(path="/user/", ref="#/paths/user~1login");
 */
function login() {
  ...
}

with the current annotations @OA\Post and @OA\PathItem but using the field ref throws an error.

Am I missing something or is this just not possible anymore?

[Doqnach]

What is the error that is thrown? Could you provide a minimal working example of what you have so people can try and reproduce?

[zFly]

Sorry, I forgot to add the exception:

Unexpected field "ref" for @OA\PathItem(), expecting "path", "summary", "get", "put", "post", "delete", "options", "head", "patch", "trace", "servers", "parameters", "x"

Stacktrace

 1    trigger_error()
      laravel-project/vendor/zircote/swagger-php/src/Logger.php:39

  2   OpenApi\Logger::OpenApi\{closure}()
      laravel-project/vendor/zircote/swagger-php/src/Logger.php:61

  3   call_user_func()
      laravel-project/vendor/zircote/swagger-php/src/Logger.php:61

  4   OpenApi\Logger::warning()
      laravel-project/vendor/zircote/swagger-php/src/Analyser.php:124

  5   OpenApi\Analyser::fromComment()
      laravel-project/vendor/zircote/swagger-php/src/StaticAnalyser.php:314

  6   OpenApi\StaticAnalyser::analyseComment()
      laravel-project/vendor/zircote/swagger-php/src/StaticAnalyser.php:224

  7   OpenApi\StaticAnalyser::fromTokens()
      laravel-project/vendor/zircote/swagger-php/src/StaticAnalyser.php:45

  8   OpenApi\StaticAnalyser::fromFile()
      laravel-project/vendor/zircote/swagger-php/src/functions.php:43

  9   OpenApi\scan()
      laravel-project/vendor/darkaonline/l5-swagger/src/Generator.php:119

  10  L5Swagger\Generator::scanFilesForDocumentation()
      laravel-project/vendor/darkaonline/l5-swagger/src/Generator.php:66

  11  L5Swagger\Generator::generateDocs()
      laravel-project/vendor/darkaonline/l5-swagger/src/Console/GenerateDocsCommand.php:32

As you can see I am using the L5-Swagger package to generate a swagger doc for my laravel project. The package heavily depends on this one where the exception gets thrown.

The error can be reproduced by adding @OA\PathItem(path="/animal", ref="#/paths/~1pet")
to the phpDoc in the petStore Example Examples/petstore-3/Controllers/Pet:addPet()

/**
     * @OA\Post(
     *     path="/pet",
     *     tags={"pet"},
     *     summary="Add a new pet to the store",
     *     operationId="addPet",
     *     @OA\Response(
     *         response=405,
     *         description="Invalid input"
     *     ),
     *     security={
     *         {"petstore_auth": {"write:pets", "read:pets"}}
     *     },
     *     requestBody={"$ref": "#/components/requestBodies/Pet"}
     * )
     *
     * @OA\PathItem(path="/animal", ref="#/paths/~1pet")
     */

Running ./bin/openapi --debug -o swagger.json ./Examples/petstore-3.0/ results in the same error.

[Doqnach]

As you can see, https://github.com/zircote/swagger-php/blob/069e6e59bb06db808961bcad1bc3cc0f82869adb/src/Annotations/PathItem.php doesn't support ref.

e.g. https://github.com/zircote/swagger-php/blob/master/src/Annotations/Schema.php#L28 does.

If it should, best would be to open a PR for it.

[bfanger]

Path Item Object does support ref https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#pathItemObject

Added support to the annotation, will be fixed in the next release.

[maxgalbu]

@bfanger PathItem cannot be used with a class method:

Error: Error: Attribute "OpenApi\Attributes\PathItem" cannot target method (allowed targets: class) in /var/www/api-core/vendor/zircote/swagger-php/src/Analysers/AttributeAnnotationFactory.php:42

How can we use the same documentation for different paths/class methods?

[DerManoMann]

I guess that would be a feature request.

See #1485

[maxgalbu]

@DerManoMann it's still not working properly, at least from the point of view of I want two paths defined on the same method. I can still do this:

#[OA\Get(
        tags: ["Hotel API"],
        path: "/v3/vendors/enable",
    )]
    #[OA\Get(
        tags: ["Hotel API"],
        path: "/v3/vendors/enable2",
    )]
public function enableSuspendedVendorsAction() {
}

... and it looks like it's working, but with the following warnings:

api-core-php-docs   | Warning: Unable to merge @OA\Get() in \ApiCore\Apps\V2\Controllers\PricingHotelController->enableSuspendedVendorsAction() in /var/www/api-core/apps/V2/Controllers/PricingHotelController.php on line 38
api-core-php-docs   | Warning: Unable to merge @OA\Get() in \ApiCore\Apps\V2\Controllers\PricingHotelController->enableSuspendedVendorsAction() in /var/www/api-core/apps/V2/Controllers/PricingHotelController.php on line 38
api-core-php-docs   | Warning: Unable to merge @OA\Get() in \ApiCore\Apps\V2\Controllers\PricingHotelController->enableSuspendedPosAction() in /var/www/api-core/apps/V2/Controllers/PricingHotelController.php on line 59
api-core-php-docs   | Warning: Unable to merge @OA\Get() in \ApiCore\Apps\V2\Controllers\PricingHotelController->suspendVendorAction() in /var/www/api-core/apps/V2/Controllers/PricingHotelController.php on line 82
api-core-php-docs   | Warning: Unable to merge @OA\Get() in \ApiCore\Apps\V2\Controllers\PricingHotelController->enableVendorAction() in /var/www/api-core/apps/V2/Controllers/PricingHotelController.php on line 117
api-core-php-docs   | Warning: Unable to merge @OA\Get() in \ApiCore\Apps\V2\Controllers\PricingHotelController->disableVendorAction() in /var/www/api-core/apps/V2/Controllers/PricingHotelController.php on line 149
api-core-php-docs   | Warning: Unable to merge @OA\Get() in \ApiCore\Apps\V2\Controllers\PricingHotelController->suspendPosAction() in /var/www/api-core/apps/V2/Controllers/PricingHotelController.php on line 183
api-core-php-docs   | Warning: Unable to merge @OA\Get() in \ApiCore\Apps\V2\Controllers\PricingHotelController->disablePosDeviceAction() in /var/www/api-core/apps/V2/Controllers/PricingHotelController.php on line 223
api-core-php-docs   | Warning: Unable to merge @OA\Get() in \ApiCore\Apps\V2\Controllers\PricingHotelController->enablePosDeviceAction() in /var/www/api-core/apps/V2/Controllers/PricingHotelController.php on line 265

[DerManoMann]

@maxgalbu You might have to give me a fully working example that reproduces this error. I've added a simple test and that works fine: #1492