CODEWITHSUNDEEP
phpopenapiswagger-php
ddruganov
ddruganov

Reputation: 1703

Swagger - "Required @OA\Info() not found"

I just got into api documentation and tried to use Swagger

here is my php file with routes that I want to document:

<?php

use OpenApi\Annotations as OA;

/**
 * @OA\Info(title="My First API", version="0.1")
 */
return [
    /**
     * @OA\Get(
     *     path="/api/v1/test",
     *     @OA\Response(response="200", description="An example resource")
     * )
     */
    'GET api/v1/test' => 'test/index',
];

But when I run ./vendor/bin/openapi api/config/routes.php cli only outputs errors:

Warning: Required @OA\Info() not found
Warning: Required @OA\PathItem() not found
openapi: 3.0.0

I then tried Swagger2 and it worked just fine

Im using php8.1 from php:8.1-fpm-alpine docker image, the latest zircote/swagger-php package and the Yii2 framework

Upvotes: 4

Views: 17170

Answers (7)

Saintilien Wilson
Saintilien Wilson

Reputation: 51

This work for me

/**

  • @OA\OpenApi(
  • @OA\Info(
  •    title="Your API Title",

  •    version="1.0.0",

  •    description="This is the API documentation for your project.",

  •    @OA\Contact(

  •        email="[email protected]"

  •    ),

  •    @OA\License(

  •        name="MIT",

  •        url="https://opensource.org/licenses/MIT"

  •    )
  • ),
  • @OA\Server(
  •    url="http://localhost:8000/api",

  •    description="Development Server"
  • )
  • ) */

Upvotes: 0

VeRJiL
VeRJiL

Reputation: 564

In your folder structure create a folder named Swagger and create a class named SwaggerDecorator and then add this annotations on top of the SwaggerDecorator:

<?php

namespace Support\Swagger;

/**
 * @OA\Info(
 *      title="The Test Api Documentation",
 *      version="1.0.0",
 *      description="The Test Api Documentation"
 *  )
 */
class SwaggerDecorator
{
    
}

You can choose what ever name and folder name you want.

and now add the following line to the l5/swagger.php package config file:

return [
    'default' => 'default',
    'documentations' => [
        /// ... other configs
                
            /*
             * Absolute paths to directory containing the swagger annotations are stored.
            */
            'annotations' => [
                base_path('app/Swagger'), // You should add this line to work
                base_path('app/'),
            ],
            
        ],
    //... other configs
    ],

Upvotes: 1

Buzka91
Buzka91

Reputation: 399

Recently i upgrade zircote/swagger-php from 4.7.15 to 4.8.3 and had same issue on one project.

https://zircote.github.io/swagger-php/guide/faq.html#warning-required-oa-info-not-found says:

As of version 4.8 the doctrine/annotations library is optional and might cause the same message. If this is the case, doctrine annotations must be installed separately: composer require doctrine/annotations

One of my projects had doctrine/annotations as dependency in another library, but my another project didn't, that caused problems with documentation wrote through PHPDocs.

So you got two options, or require missing dependency or rewrite code as below (PHP8+):

/**
 * REST API route base class.
 *
 * @OA\Info(
 *     title="Test API REST",
 *     version="latest",
 *     description="test"
 * )
 */

Replace with:

#[\OpenApi\Attributes\Info(
    title: "Test API REST",
    version: "latest",
    description: "test",
)]

Upvotes: 0

adnan ahmady
adnan ahmady

Reputation: 960

I updated the darkaonline/l5-swagger for Laravel framework and this third-party library is using zircote/swagger-php library behind the scene, after updating to version "darkaonline/l5-swagger": "^8.5" I faced a similar issue like bellow.

Required @OA\Info() not found
at vendor/zircote/swagger-php/src/Loggers/DefaultLogger.php

I added swagger to the project long before PHP introduced Attributes, and at that time, for generating swagger information, annotations were being used therefore you could have files only containing annotations (which by the way for a big project, having shared components is a lifesaver).

For example, you could separate different types of shared components in their own files, in this way maintaining a project that offers swagger documentation will be way much easier, and this method was working just fine. I had some files for core like @OA\Info and shared components like below.

<?php

/**
 * @OA\Info(
 *      version="1.0.0",
 *      title="API Documentation",
 *      description="Description removed for better illustration of structure.",
 *      @OA\Contact(
 *          email="[email protected]",
 *          name="company",
 *          url="https://example.test"
 *      ),
 *      @OA\License(
 *          name="Apache 2.0",
 *          url="http://www.apache.org/licenses/LICENSE-2.0.html"
 *      )
 * )
 */

After updating the library, the mentioned error roused and the cause is that an annotation is basically documentation or comment text, thus the programming language automatically ignores it, therefore the @OA phrase is basically just a text and not anything more.

After PHP introduced Attributes the third-party library developer tried to support attributes as well, and since an attribute is carrying metadata and it's handled by PHP itself, it needs to get attached to some concept like class or function, it seems the developer didn't see some edge case and the so-called edge case is the applications using annotations for a long time, may implement them in separate files only containing the documentation or comment, and no other programming concepts like function or any other thing.

Therefore to fix the issue I just needed to change the files containing the annotations into class files and add some empty classes under the documentation and autoload the created classes.

In this way, the third-party library reads the annotations like before.

So I renamed the setup.php file to Setup.php as PSR-4 the autoloading standard requires for class names and updated the content like below.

<?php

namespace App\Your\Path\Swagger;

/**
 * @OA\Info(
 *      version="1.0.0",
 *      title="API Documentation",
 *      description="Description removed for better illustration of structure.",
 *      @OA\Contact(
 *          email="[email protected]",
 *          name="company",
 *          url="https://example.test"
 *      ),
 *      @OA\License(
 *          name="Apache 2.0",
 *          url="http://www.apache.org/licenses/LICENSE-2.0.html"
 *      )
 * )
 */
final class Setup
{
    //
}

after converting the file into a class, I just had to tell the composer to automatically load classes in the App/Your/Path/Swagger path in the composer.json file like below.

"autoload": {
    "psr-4": {
        "App\\": "app/"
    },
    "classmap": [
        "App/Your/Path/Swagger",
        "database/seeds",
        "database/factories"
    ]
},

In this way, the problem is solved. just remember that if you have shared component files, you need to change them too.

Upvotes: 2

Firdavs
Firdavs

Reputation: 109

Here is solution https://github.com/DarkaOnLine/L5-Swagger/issues/443

Add in your base Controller

<?php

namespace App\Http\Controllers;

use Illuminate\Foundation\Bus\DispatchesJobs;
use Illuminate\Routing\Controller as BaseController;
use Illuminate\Foundation\Validation\ValidatesRequests;
use Illuminate\Foundation\Auth\Access\AuthorizesRequests;

/**
 * @OA\Info(title="My First API", version="0.1")
 */
class Controller extends BaseController
{
    use AuthorizesRequests, DispatchesJobs, ValidatesRequests;
}

Upvotes: 10

ddruganov
ddruganov

Reputation: 1703

Turns out openapi was not autoloading classes from my subfolders

The solution is very simple: generate docs from inside of a console application (for example I have a php yii open-api/generate-docs command)

That way composer and yii2 load all of the classes needed for swagger

You also have to anchor all of the attributes to specific classes so the approach in the original question will not work; my solution was to create a compiled router with each route having a separate class with php8.1 attributes

Upvotes: 0

DerManoMann
DerManoMann

Reputation: 529

Alternatively, you could also add -b ./vendor/autoload.php to the openapi command to setup autoloading for swagger-php.

Either way I am surprised that this works with swagger-php v4 as that requires annotations to be anchored to a structural element (class, interface, etc.)

The main idea here is to annotate your actual controllers (or whatever it is called in your framework), so the code that handles a request so the documentation is close to the actual code.

Upvotes: 1

Related Questions