Swagger-php is a PHP library that generates OpenAPI documentation from PHP attributes or doctrine annotations.
The tool solves the problem of keeping API documentation in sync with code by extracting metadata directly from PHP source files. Developers annotate their classes, methods, and other structural elements with OpenAPI attributes or doctrine annotations, and the library parses these annotations to generate a complete OpenAPI specification. The library supports OpenAPI 3.0, 3.1, and 3.2 specifications and can resolve complex types using the symfony/type-info library. It offers both programmatic and command-line interfaces for generating documentation as static YAML or JSON files.
Teams should adopt this tool if they maintain RESTful APIs in PHP and want documentation that stays current with code changes. It works well for projects where developers are already familiar with PHP attributes or annotations. The tool requires PHP 8.2 or later. Doctrine annotations are now optional and must be installed separately if needed. The library includes a beta spec attributes pipeline that provides an alternative processing mode with typed data transfer objects and version-aware compilers, available through hybrid mode for gradual migration from existing code.
The project maintains active development with regular updates to support new OpenAPI versions and PHP features. The codebase includes comprehensive error reporting with hints and context to guide users through configuration issues. A beta processing pipeline demonstrates ongoing architectural evolution, offering users an optional path to modernized internals without requiring immediate migration. The tool provides both classic and hybrid processing modes, allowing teams to adopt new features incrementally alongside existing implementations.
