TopGit tracks zircote/swagger-php on GitHub. The project has 5.3k stars. A php swagger annotation and parsing library
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
Generate interactive OpenAPI documentation for your RESTful API
using PHP attributes.
See the documentation website for supported
attributes.
Features
Compatible with the OpenAPI 3.0, 3.1 and 3.2 specification.
Extracts information from code and existing phpdoc comments.
Can be used programmatically or via command-line tool.
Error reporting (with hints, context).
Spec attributes: attributes that can also be built by hand and compiled without scanning, and a pipeline that reports when an attribute is wrong. See Why spec attributes?.
OpenAPI version support
swagger-php can generate specs for OpenAPI 3.0.0, OpenAPI 3.1.0 and OpenAPI 3.2.0.
Classic mode defaults to 3.0.0, spec and hybrid mode to 3.1.0.
The command line option --version selects a different version; programmatically, use
Builder::setVersion().
Requirements
swagger-php requires at least PHP 8.2.
Installation (with Composer)
composer require zircote/swagger-php
For cli usage from anywhere, install swagger-php globally and add Composer's global binary directory
(composer global config bin-dir --absolute) to your PATH, so the openapi executable can be located by
your system.
composer global require zircote/swagger-php
doctrine/annotations (deprecated)
As of version 4.8 the doctrine annotations library is
optional and no longer installed by default.
If your code uses doctrine annotations you will need to install that library manually:
composer require doctrine/annotations
Usage
Use OpenAPI attributes to add metadata to your classes, methods and other structural PHP elements.
use OpenApi\Spec as OA;
#[OA\Info(title: 'My First API', version: '0.1')]
class MyApi
{
#[OA\Operation\Get(path: '/api/resource.json')]
#[OA\Response(response: 200, description: 'An example resource')]
public function getResource()
{
// ...
}
}
Visit the Documentation website for
the Getting started guide or look at
the examples directory for more examples.
Classic attributes and docblock annotations
Deprecated since 7.0, removed in 8.0.
Classic attributes in OpenApi\Attributes and docblock annotations still work, in hybrid and in classic
mode. Hybrid, the default, scans them and hands them to the same pipeline as the attributes above.
Classic mode builds them with its own pipeline, as in 6.x.
use OpenApi\Attributes as OAT;
#[OAT\Info(title: 'My First API', version: '0.1')]
class MyApi
{
#[OAT\Get(path: '/api/resource.json')]
#[OAT\Response(response: '200', description: 'An example resource')]
public function getResource()
{
// ...
}
}
Migrating to spec attributes covers the move,
and Processing Modes compares the modes.
Builder is the entry point, and one instance builds one document.
See the Builder reference for its API.
Details on how to generate OpenApi specifications can be found
in the generate reference.
Usage from the Command Line Interface
The openapi command line interface can be used to generate the documentation to a static yaml/json file.
./vendor/bin/openapi --help
Automatic type resolution
Types are resolved with the symfony/type-info library. swagger-php supports all native type hints and also
generic type hints in phpdoc blocks. This simplifies the definition of schemas.
For example, the following two examples are equivalent:
class MyClass
{
#[OA\Schema\Items(oneOf: [
new OA\Schema(ref: SchemaOne::class),
new OA\Schema(ref: SchemaTwo::class),
])]
public array $values;
}
class MyClass
{
/**
* @var list<SchemaOne|SchemaTwo>
*/
#[OA\Property]
public array $values;
}
zircote/swagger-php has 5.3k GitHub stars — refresh the page for the live number, or check github.com/zircote/swagger-php. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
Is zircote/swagger-php open source?
Yes — zircote/swagger-php ships under the Apache-2.0 license, which makes its source code freely readable (and, depending on license terms, forkable and reusable). Source: github.com/zircote/swagger-php.
What is zircote/swagger-php?
zircote/swagger-php (zircote/swagger-php) is a PHP project on GitHub. From the project's own README: A php swagger annotation and parsing library
Where can I see zircote/swagger-php in action?
The project maintains a homepage at http://zircote.github.io/swagger-php/. The README tab on this page also usually contains screenshots and a quickstart.
Where do I read more about zircote/swagger-php?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/zircote/swagger-php is the definitive source.
Read full README in the tab above.
Still deciding about swagger-php?
One click hands the question to an AI along with this page — see what it says about swagger-php.