README

OpenAPI 3.0.0 spec generator for the ez-php framework. Annotate controller methods with PHP attributes and get a live GET /openapi.json endpoint — no code generation, no annotation parsing framework, no YAML.

Installation

composer require ez-php/openapi

Register the service provider in provider/modules.php:

$app->register(\EzPhp\OpenApi\OpenApiServiceProvider::class);

Usage

Add attributes to your controller methods:

use EzPhp\OpenApi\Attributes\ApiOperation;
use EzPhp\OpenApi\Attributes\ApiParam;
use EzPhp\OpenApi\Attributes\ApiResponse;

final class UserController
{
    #[ApiOperation(summary: 'List users', tags: ['users'])]
    #[ApiResponse(200, 'List of users')]
    #[ApiParam('search', 'string', 'query', false, 'Filter by name')]
    public function index(Request $request): Response { ... }

    #[ApiOperation(summary: 'Get user')]
    #[ApiResponse(200, 'The user', UserSchema::class)]
    #[ApiResponse(404, 'Not found')]
    #[ApiParam('id', 'integer', 'path', true, 'The user ID')]
    public function show(Request $request): Response { ... }
}

Visit GET /openapi.json to retrieve the generated spec.

Attributes

#[ApiOperation]

Not repeatable — one per method.

#[ApiResponse]

Repeatable — multiple responses per method.

#[ApiParam]

Repeatable — multiple parameters per method.

Configuration

Notes

• Only [Controller::class, 'method'] handler routes are reflected for attributes. Closure-based routes appear in the spec without attribute data.
• Path parameters ({id}) are auto-detected from route patterns and added as in: 'path', required: true, type: 'string' when not explicitly declared via #[ApiParam].
• Component schemas (#/components/schemas/...) referenced by $schemaClass must be registered separately — this module generates the $ref but not the schema definition.