Swagger Php Laravel Package

Getting Started

Install via Composer (composer require zircote/swagger-php). Annotate your controller or DTO classes using @OA\ annotations (e.g., @OA\Get, @OA\Response, @OA\Property). Generate OpenAPI JSON/YAML using the Symfony Console-based CLI tool (php vendor/bin/openapi -o public/docs/openapi.json src/). For programmatic generation, use OpenApi\Generator::generate(). First use case: Document a REST endpoint with request/response examples and validation rules via 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 php vendor/bin/openapi in CI to validate schema consistency (now leveraging Symfony Console).
• Laravel integration: Register a service provider to scan controllers automatically using Generator::scan(), and define global metadata via @OA\Info.
• Example-driven docs: Use corrected object creation patterns (fixed in PR #1976) for accurate OpenAPI examples.

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: Place @OA\ annotations before PHPDoc comments (e.g., /** @var string */) to avoid conflicts.
• Extensibility: Extend OpenApi\Analysis for custom processing (e.g., annotations, validation rules).
• Debugging:
  • Use --verbose with the CLI (php vendor/bin/openapi --verbose).
  • Inspect OpenApi\Analysis::$lastError for parsing issues.
  • Ensure paths are absolute and scanned directories exist.
• CLI improvements: The bin/openapi tool now uses Symfony Console (PR #1977), enabling better error handling and flags (e.g., --help).
• No ext-json dependency: The package no longer requires the JSON extension (PR #1974), reducing deployment friction.
• Version compatibility: Ensure Laravel swagger-php version matches PHP version (v6.1.0+ requires PHP 8.0+).