swagger-php

swagger-php generates interactive OpenAPI (formerly Swagger) documentation for RESTful APIs written in PHP. You describe your API using native PHP attributes (preferred) or Doctrine annotations placed alongside your code, and swagger-php scans the source to produce a compliant OpenAPI specification in JSON or YAML.

It supports the OpenAPI 3.0, 3.1, and 3.2 specifications, extracts information from existing PHPDoc, and can be run either programmatically via the Generator class or through the bundled openapi command-line tool. It is the parsing engine behind many Laravel and Symfony API-documentation packages.

What You Get

• OpenAPI 3.0, 3.1, and 3.2 spec generation from PHP source
• Native PHP attribute support (with legacy Doctrine annotation support)
• A Generator class for programmatic use and a bin/openapi CLI tool
• Extraction of details from existing PHPDoc and a processor pipeline for customization

Common Use Cases

• Auto-generating OpenAPI specs from an annotated PHP REST API
• Powering Swagger UI / interactive API docs in Laravel or Symfony apps
• Producing an OpenAPI file in CI to publish or lint API contracts

Under The Hood

Architecture — The Generator orchestrates a pipeline: a SourceFinder collects PHP files, analysers (backed by nikic/php-parser and phpstan/phpdoc-parser) build an Analysis model of discovered annotations/attributes, a chain of Processors normalizes and links them (merging, augmenting, cleaning), and a Serializer emits the final OpenAPI document. Attribute and annotation classes under Attributes/Annotations model the spec; Console wires the bin/openapi CLI via Symfony Console.

Tech Stack — PHP 8.2+, depending on nikic/php-parser, phpstan/phpdoc-parser, symfony/console, symfony/finder, symfony/yaml, and psr/log. Output targets OpenAPI 3.0-3.2.

Code Quality — A large, mature, and actively maintained codebase (health 94) with clear separation between analysis, processing, and serialization, plus interfaces (CompilerInterface, TypeResolverInterface) for extensibility. It has an extensive test suite and strong CI.

API Design — The attribute-based API is expressive and reads close to the OpenAPI spec, and both the Generator programmatic entry point and the openapi CLI are straightforward. The main learning cost is the breadth of available attributes, mitigated by thorough documentation on the project’s website.