swagger-php
A PHP library for generating OpenAPI documentation from PHP attributes or annotations.
What is swagger-php?
swagger-php is a PHP library that generates interactive OpenAPI documentation for RESTful APIs. It extracts metadata directly from PHP code using modern PHP attributes or, for backward compatibility, Doctrine annotations, and supports OpenAPI specifications 3.0, 3.1, and 3.2.
PHP developers building RESTful APIs who need to generate and maintain accurate, up-to-date OpenAPI documentation directly from their codebase.
Developers choose swagger-php for its modern, attribute-based approach that integrates seamlessly with PHP 8.2+, offering automatic type resolution for complex generic type-hints and providing both programmatic and CLI usage options for flexible integration into development workflows.
Overview
A php swagger annotation and parsing library
Use Cases
Best For
- Generating OpenAPI documentation for PHP-based RESTful APIs directly from source code.
- Projects requiring support for the latest OpenAPI specifications (3.0, 3.1, or 3.2).
- Teams adopting modern PHP 8.2+ features like attributes for clean, type-safe API configuration.
- Automating API documentation updates as code changes, ensuring documentation stays synchronized.
- Integrating OpenAPI generation into CI/CD pipelines via its command-line interface.
- Handling complex type definitions in PHP code with automatic resolution via PHPDoc blocks.
Not Ideal For
- Projects using PHP versions below 8.2, as swagger-php has a strict minimum requirement of PHP 8.2.
- Teams that prefer maintaining OpenAPI specifications in separate YAML/JSON files rather than embedding metadata directly in code.
- Applications needing live, interactive API documentation without manual generation steps; swagger-php only produces static OpenAPI spec files.
- Legacy codebases heavily reliant on Doctrine annotations, since annotations are deprecated and may be removed in future releases.
Pros & Cons
Pros
Supports OpenAPI 3.0, 3.1, and 3.2 specifications, allowing developers to adopt the latest standards and switch versions via CLI or programmatically.
Utilizes PHP 8.2+ attributes for clean, type-safe configuration, reducing boilerplate and aligning with contemporary PHP development practices as highlighted in the README.
Leverages symfony/type-info to automatically resolve complex generic type-hints from PHPDoc blocks, simplifying schema definitions without manual attribute configuration.
Offers both programmatic access via the Generator class and a command-line interface, enabling integration into various workflows like CI/CD pipelines or runtime documentation generation.
Cons
Requires PHP 8.2 or higher, which excludes projects on older PHP versions and may force costly upgrades or limit adoption in legacy environments.
Doctrine annotations are deprecated and may be removed in future releases, creating a migration burden for existing codebases and adding complexity if the doctrine/annotations library is still needed.
Only generates OpenAPI specification files; developers must separately integrate tools like Swagger UI for interactive documentation, adding an extra step to the workflow.
If using annotations, the doctrine/annotations library must be manually installed as an extra dependency, increasing setup overhead and potential version conflicts.
Frequently Asked Questions
Related Projects
ScrambleModern Laravel OpenAPI (Swagger) documentation generator. No PHPDoc annotations required.
APIGenPHP 7.1 ready Smart and Simple Documentation for your PHP project
daux.ioDaux.io is an documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly. It helps you create great looking documentation in a developer friendly way.
phpDoxA documentation generator for PHP projects (that is not limited to API documentation)
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.