API with no endpoints throws exception Required @OA\\PathItem() not found

zircote / swagger-php

A php swagger annotation and parsing library

http://zircote.github.io/swagger-php/

Apache License 2.0

5.07k stars 933 forks source link

API with no endpoints throws exception Required @OA\\PathItem() not found #1449

Closed savedario closed 9 months ago

savedario commented 1 year ago

If there are no endpoints defined either with @OA\ or with @OA\PathItem, the swagger page shows no output and the application logs the exception:

Required @OA\PathItem() not found at /project/vendor/zircote/swagger-php/src/Loggers/DefaultLogger.php:31

which is a rather misleading message.

Note: other annotations are in use (Info, Server, SecurityScheme, Flow) that were obviously referring to yet-to-be-developed endpoints, but that does not seem to be a problem just to generate the swagger page.

DerManoMann commented 1 year ago

The spec ifself just describes endpoints. Whether those endpoints exist or not does not really matter here. They might be password protected, behind a firewall or not yet exist.

However, for an OpenAPI spec to make sense it needs to contain endpoints (as that is the main point).

If you already have other annotations that describe yet to be developed features, why not also add a (simple/dummy) endpoint to get things going?

savedario commented 1 year ago

My original intention was not to ask a question but to signal an issue that could be fixed by either:

throwing an exception with a more descriptive message when no endpoints are detected or...
consider that OpenAPI (in my case league/openapi-psr7-validator) allows to define an API with no endpoints (whether that make sense or not) and leave that part of the page just... empty ?

I did add a dummy endpoint, but it took a while to figure out that was "the problem".

potsky commented 9 months ago

Upgrading from 4.7.16 to 4.8.1 produces the same problem on our Laravel installation but all PHP files have a @OA<method>...

Screenshot 2023-12-13 - 19-20-06@2x

I tried to find from where comes this problem but without any success 😢

Do you have an advice to help us find where is the file causing a problem?

DerManoMann commented 9 months ago

As of 4.8 the doctrine/annotations package is optional, which also causes this error - as no annotations are parsed. Maybe the error message could be improved.

potsky commented 9 months ago

Thank you @DerManoMann, indeed, adding "doctrine/annotations": "^2.0" to our composer.json works 🎉