Warning skipping .... errors even with bootstrap option specified.

[hookenz]

30 years as a software engineer and I simply must be too dumb to get this working.

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

When things don't work out I usually go to a minimal example. So I took one from your doc pages:

I named this file openapi.php and placed it into my src directory.

<?php

use OpenApi\Attributes as OA;

#[OA\Info(title: "My First API", version: "0.1")]
class OpenApi
{
}

class MyController
{

    #[OA\Get(path: '/api/data.json')]
    #[OA\Response(response: '200', description: 'The data')]
    public function getResource()
    {
        // ...
    }
}

Put that into a directory called OpenApiTest\src (it's the only file in there)
Then in the OpenApiTest directory containing only the src folder

❯ composer require zircote/swagger-php
./composer.json has been created
Running composer update zircote/swagger-php
Loading composer repositories with package information
Updating dependencies
Lock file operations: 6 installs, 0 updates, 0 removals
  - Locking psr/log (3.0.2)
  - Locking symfony/deprecation-contracts (v3.5.1)
  - Locking symfony/finder (v7.2.0)
  - Locking symfony/polyfill-ctype (v1.31.0)
  - Locking symfony/yaml (v7.2.0)
  - Locking zircote/swagger-php (4.11.1)
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 6 installs, 0 updates, 0 removals
  - Installing symfony/polyfill-ctype (v1.31.0): Extracting archive
  - Installing symfony/deprecation-contracts (v3.5.1): Extracting archive
  - Installing symfony/yaml (v7.2.0): Extracting archive
  - Installing symfony/finder (v7.2.0): Extracting archive
  - Installing psr/log (3.0.2): Extracting archive
  - Installing zircote/swagger-php (4.11.1): Extracting archive
1 package suggestions were added by new dependencies, use `composer suggest` to see details.
Generating autoload files
4 packages you are using are looking for funding.
Use the `composer fund` command to find out more!
No security vulnerability advisories found.
Using version ^4.11 for zircote/swagger-php

~/openapitest via 🐘 took 3s
❯ ./vendor/bin/openapi src/ -o openapi.yaml
Warning: Skipping unknown \OpenApi
Warning: Skipping unknown \MyController
Warning: Required @OA\PathItem() not found
Warning: Required @OA\Info() not found

Maybe the bootstrap option will make it work?

~/openapitest via 🐘
❯ ./vendor/bin/openapi -b vendor/autoload.php src/ -o openapi.yaml
Warning: Skipping unknown \OpenApi
Warning: Skipping unknown \MyController
Warning: Required @OA\PathItem() not found
Warning: Required @OA\Info() not found

And several other attempts all resulting in failure with the exact same error every single time. When I tried to get this working
with my project it was the same error messages and the same "skipping unknown" errors for all my classes. Despite having autoload running, or even providing the bootstrap option. No difference.

The version installed of swagger-php and PHP

❯ cat composer.json
{
    "require": {
        "zircote/swagger-php": "^4.11"
    }
}

❯ php --version
PHP 8.3.11 (cli) (built: Oct  7 2024 11:19:48) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.3.11, Copyright (c) Zend Technologies
    with Zend OPcache v8.3.11, Copyright (c), by Zend Technologies

I also tried the older style annotations and installed the doctrine requirement. Again, the result was identical.
So it's not that. I'm just not sure how to make this project produce anything useful.

How do I get this working?
What am I doing wrong? This error seems to occur a lot and your documentation and examples all look to be old and certainly don't work. If I can't get it working I'm not sure how a complete beginner is meant to.

Is it perhaps a bug in the most recent version or some key missing step?
I would have expected it to produce something meaningful but all that it produced was a file container

❯ cat openapi.yaml
openapi: 3.0.0

To clarify.

The directory structure is

❯ find openapitest
❯ find openapitest/
openapitest/
openapitest/src
openapitest/src/openapi.php
openapitest/composer.lock
openapitest/vendor
openapitest/vendor/zircote
openapitest/vendor/zircote/swagger-php
openapitest/vendor/zircote/swagger-php/src

-- snip ---

openapitest/vendor/bin/openapi
openapitest/vendor/autoload.php
openapitest/openapi.yaml
openapitest/composer.json

[DerManoMann]

Well, it's still the autoloading. Putting a class MyController into a file called openapi.php does not conform to any PSR autoloading standard. Also, for vendor/autoload.php to work you would need to configure where to look for source code anyway.

Two ways to make your test work:

1. Add autoload config to your composer.json:

{
    "require": {
        "zircote/swagger-php": "^4.11"
    },
    "autoload": {
        "files": [
            "src/openapi.php"
        ]
    }
}

After this change you will also need to run composer dump to make it pick up the change.

2. Use your test file as bootstrap:

./vendor/bin/openapi -b src/openapi.php src -o openapi.yaml

Hope this helps.

[hookenz]

I wasn't really aware of the PSR autoload standard. So that helped somewhat. I put the classes into their own files named after the class name following the standard.

I added an autoload to the composer.json.

I modified the two files:

<?php
namespace App;

use OpenApi\Annotations as OA;

class MyController
{
    #[OA\Get(path: '/api/data.json')]
    #[OA\Response(response: '200', description: 'The data')]
    public function getResource()
    {
        // ...
    }
}

and

<?php
namespace App;

use OpenApi\Annotations as OA;

#[OA\Info(title: "My First API", version: "0.1")]
class OpenApi
{
}

❯ cat composer.json
{
    "require": {
        "zircote/swagger-php": "^4.11"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

But now when I run openapi I get this error:

❯ ./vendor/bin/openapi src -o openapi.yaml
Error: Error: Attempting to use non-attribute class "OpenApi\Annotations\Get" as attribute in /home/hookenz/openapitest/vendor/zircote/swagger-php/src/Analysers/AttributeAnnotationFactory.php:47
Stack trace:
#0 /home/hookenz/openapitest/vendor/zircote/swagger-php/src/Analysers/AttributeAnnotationFactory.php(47): ReflectionAttribute->newInstance()
#1 /home/hookenz/openapitest/vendor/zircote/swagger-php/src/Analysers/ReflectionAnalyser.php(139): OpenApi\Analysers\AttributeAnnotationFactory->build(Object(ReflectionMethod), Object(OpenApi\Context))
#2 /home/hookenz/openapitest/vendor/zircote/swagger-php/src/Analysers/ReflectionAnalyser.php(63): OpenApi\Analysers\ReflectionAnalyser->analyzeFqdn('App\\MyControlle...', Object(OpenApi\Analysis), Array)
#3 /home/hookenz/openapitest/vendor/zircote/swagger-php/src/Generator.php(537): OpenApi\Analysers\ReflectionAnalyser->fromFile('src/MyControlle...', Object(OpenApi\Context))
#4 /home/hookenz/openapitest/vendor/zircote/swagger-php/src/Generator.php(497): OpenApi\Generator->scanSources(Object(Symfony\Component\Finder\Finder), Object(OpenApi\Analysis), Object(OpenApi\Context))
#5 /home/hookenz/openapitest/vendor/zircote/swagger-php/bin/openapi(233): OpenApi\Generator->generate(Object(Symfony\Component\Finder\Finder))
#6 /home/hookenz/openapitest/vendor/bin/openapi(119): include('/home/hookenz/o...')
#7 {main}

I had a bit of a read about attribute classes and added something to the OpenApi file. Specifically

use Attribute;

#[Attribute]

But it didn't resolve the problem. Do you have a small working example? I'm from PHP of 10+ years ago and so much of what I'm learning here is new to me, including PSR standards.

[hookenz]

Solved it! thankyou @DerManoMann .
I had switched to annotation version and then realized it should be the attribute version. Now it's working. I think I should now be able to get this working in my project now that I have a working example.

As a bit of feedback it would be good to have some basic documentation around this for those coming from other languages or who like me were a bit out of date in using more recent PHP features.

I'm happy to help in that regard.