repository·master·Indexed 26 days ago
https://github.com/zircote/swagger-phpA PHP library used to generate interactive OpenAPI documentation for RESTful APIs using PHP 8+ attributes or Doctrine annotations. It includes a CLI tool (bin/openapi) to scan source code and output specifications. Key features include automatic augmentation of schema data types, summary, and description fields from PHP docblocks and type hints, as well as a processor pipeline for transforming raw analysis into valid OpenAPI specifications.
swagger-php is a library designed to extract API metadata directly from your PHP source code. It works by scanning your codebase for annotations or attributes placed next to your PHP code. The library then converts these metadata declarations into machine-readable OpenAPI documentation. This approach allows you to maintain your API documentation in the same file as your implementation, ensuring they stay synchronized.The following projects are related to swagger-php and can be used to extend its functionality, integrate it with specific frameworks, or visualize the generated documentation:
swagger.json file.NelmioApiDocBundle (bundle built on top of swagger-php) and OpenAPI-Symfony-Routing (loads routes in Symfony based on OpenAPI annotations).Lumen swagger and Laravel Swagger (OpenApi or Swagger integration for Laravel).yii2-swagger (integration for Yii2).silex2swagger (generates documentation from Silex annotations).swagger-php.swagger-php.swagger-php is a PHP library that generates OpenAPI specification documents from PHP source code by scanning annotations (PHP 8+ attributes or legacy docblock comments).
Key concepts include:
Swagger-php offers three processing modes that determine how source code is transformed into an OpenAPI document. While all modes produce equivalent OpenAPI output, they differ in their internal pipelines and attribute support.
| Mode | Status | Attributes | Annotations | Best For |
|---|---|---|---|---|
| Classic | Stable | OpenApi\Attributes | Yes | Existing projects |
| Hybrid | Beta | OpenApi\Attributes | Yes | Gradual migration |
| Spec | Beta | OpenApi\Spec | No | New projects |
The Spec Attributes pipeline (Beta) is a modern replacement for the classic annotation-based pipeline, utilizing PHP 8.1+ attributes. It separates the collection of user-defined attributes from the generation of the OpenAPI document through a five-stage process:
resolve → reduce → augment pipeline.This architecture ensures that attributes are immutable data containers and that serialization logic is decoupled from the attribute definitions themselves.
The swagger-php spec attributes pipeline follows a structured flow to transform source files into an OpenAPI document:
The swagger-php generation process follows these steps:
Generator iterates over provided sources (such as a Symfony Finder instance or a list of files/directories).AnalyserInterface (defaulting to ReflectionAnalyser) reads the files and constructs an Analysis object.Analysis object and its contained annotations are passed through configured processors.OpenApi annotation, which aggregates all annotations, is serialized into the final YAML or JSON output.During the generation process, annotations move through several lifecycle stages:
swagger-php supports native enum types. You can reference an enum in your schema just as you would with a class name. The generated OpenAPI specification will correctly represent the enum as a string with the corresponding allowed values.Use the ./vendor/bin/openapi command line tool to scan your project and generate OpenAPI documentation. By default, the output format is YAML. If you provide a filename via --output or -o, the tool determines the format based on the file extension. You can force a format using the --format option.
./vendor/bin/openapi app -o openapi.yaml#[OA\Schema]. This allows you to define the enum as a reusable component in your OpenAPI specification that can be referenced via $ref in other schemas.setMode method on your Builder instance with the 'spec' argument. In version 7, this will become the default mode.