Swagger Php Laravel Package

Getting Started

Start by installing via Composer (composer require zircote/swagger-php). Then, annotate your controller or DTO classes using @OA\ annotations (e.g., @OA\Get, @OA\Response, @OA\Property). Generate OpenAPI JSON/YAML by running openapi -o public/docs/openapi.json src/ (CLI tool included) or integrate OpenApi\Generator::generate() in your app. First use case: documenting a simple REST endpoint with request/response examples and validation rules using annotations.

Implementation Patterns

• Controller-level: Annotate routes with @OA\Get(path="/users") + @OA\Parameter, @OA\Response to describe HTTP behavior.
• DTO/Request classes: Use @OA\Schema, @OA\Property, and @OA\Items to define typed request/response bodies.
• Middleware-driven docs: Hook into route resolution to auto-generate per-request samples or context-specific metadata.
• Static analysis integration: Run openapi as part of CI to validate schema consistency.
• Integration with Laravel: Register a service provider that registers annotations via @OA\Info, and scan controllers automatically using Generator::scan().

Gotchas and Tips

• Scalar types require explicit annotations: PHP 7.4+ scalar types (e.g., int, string) are not auto-inferred; use @OA\Property(type="integer") explicitly.
• Circular references: Nesting models with mutual references may crash generation; use @OA\Property(ref="...") carefully or annotate with @OA\Discriminator.
• Annotation parsing order matters: Place @OA\ annotations before PHPDoc comments (e.g., /** @var string */) to avoid conflicts.
• Extensibility: Extend OpenApi\Analysis to add custom processing (e.g., custom annotations, validation rules).
• Debugging: Use --verbose with CLI or dump OpenApi\Analysis::$lastError to inspect parsing issues; paths must be absolute and scanned directories must exist.
• Version compatibility: Ensure Laravel swagger-php version matches PHP version (e.g., v4+ requires PHP 8.0+).