zircote / swagger-php
swagger-php - Generate interactive documentation for your RESTful API using phpdoc annotations
Installs: 93 178 612
Dependents: 427
Suggesters: 8
Security: 0
Stars: 5 104
Watchers: 94
Forks: 937
Open Issues: 49
Requires
- php: >=7.2
- ext-json: *
- psr/log: ^1.1 || ^2.0 || ^3.0
- symfony/deprecation-contracts: ^2 || ^3
- symfony/finder: >=2.2
- symfony/yaml: >=3.3
Requires (Dev)
- composer/package-versions-deprecated: ^1.11
- doctrine/annotations: ^1.7 || ^2.0
- friendsofphp/php-cs-fixer: ^2.17 || 3.62.0
- phpstan/phpstan: ^1.6
- phpunit/phpunit: >=8
- vimeo/psalm: ^4.23
Suggests
- doctrine/annotations: ^1.7 || ^2.0
- dev-master / 4.x-dev
- 4.11.1
- 4.11.0
- 4.10.7
- 4.10.6
- 4.10.5
- 4.10.4
- 4.10.3
- 4.10.2
- 4.10.1
- 4.10.0
- 4.9.3
- 4.9.2
- 4.9.1
- 4.9.0
- 4.8.7
- 4.8.6
- 4.8.5
- 4.8.4
- 4.8.3
- 4.8.2
- 4.8.1
- 4.8.0
- 4.7.16
- 4.7.15
- 4.7.14
- 4.7.13
- 4.7.12
- 4.7.11
- 4.7.10
- 4.7.9
- 4.7.8
- 4.7.4
- 4.7.3
- 4.7.2
- 4.7.1
- 4.7.0
- 4.6.2
- 4.6.1
- 4.6.0
- 4.5.6
- 4.5.5
- 4.5.4
- 4.5.3
- 4.5.2
- 4.5.1
- 4.5.0
- 4.4.10
- 4.4.9
- 4.4.8
- 4.4.7
- 4.4.6
- 4.4.5
- 4.4.4
- 4.4.3
- 4.4.2
- 4.4.1
- 4.4.0
- 4.3.0
- 4.2.15
- 4.2.14
- 4.2.13
- 4.2.12
- 4.2.11
- 4.2.10
- 4.2.9
- 4.2.8
- 4.2.7
- 4.2.6
- 4.2.5
- 4.2.4
- 4.2.3
- 4.2.2
- 4.2.1
- 4.2.0
- 4.1.1
- 4.1.0
- 4.0.5
- 4.0.4
- 4.0.3
- 4.0.2
- 4.0.1
- 4.0.0
- 4.0.0-RC1
- 3.x-dev
- 3.3.7
- 3.3.6
- 3.3.5
- 3.3.4
- 3.3.3
- 3.3.2
- 3.3.1
- 3.3.0
- 3.2.3
- 3.2.2
- 3.2.1
- 3.2.0
- 3.1.0
- 3.0.5
- 3.0.4
- 3.0.3
- 3.0.2
- 3.0.1
- 3.0.0
- 2.x-dev
- 2.1.13
- 2.1.2
- 2.1.1
- 2.1.0
- 2.0.16
- 2.0.15
- 2.0.14
- 2.0.13
- 2.0.12
- 2.0.11
- 2.0.10
- 2.0.9
- 2.0.8
- 2.0.7
- 2.0.6
- 2.0.5
- 2.0.4
- 2.0.3
- 2.0.2
- 2.0.1
- 2.0.0
- 1.0.0
- 0.9.6
- 0.9.5
- 0.9.4
- 0.9.3
- 0.9.2
- 0.9.1
- 0.9.0
- 0.8.3
- 0.8.2
- 0.8.1
- 0.8.0
- 0.7.3
- 0.7.2
- 0.7.1
- 0.7.0
- 0.6.1
- 0.6.0
- 0.4.3
- 0.4.2
- 0.4.1
- 0.4.0
- 0.3.0
- 0.2.1
- 0.1.0
This package is not auto-updated.
Last update: 2024-12-15 20:55:16 UTC
README
swagger-php
Generate interactive OpenAPI documentation for your RESTful API using PHP attributes (preferred) or
doctrine annotations (requires additional doctrine/annotations
library).
See the documentation website for supported attributes and annotations.
Annotations are deprecated and may be removed in a future release of swagger-php.
Features
- Compatible with the OpenAPI 3.0 and 3.1 specification.
- Extracts information from code & existing phpdoc annotations.
- Command-line interface available.
- Documentation site with a getting started guide.
- Exceptional error reporting (with hints, context)
- As of PHP 8.1 all annotations are also available as PHP attributes
OpenAPI version support
swagger-php
allows to generate specs either for OpenAPI 3.0.0 or OpenAPI 3.1.0.
By default the spec will be in version 3.0.0
. The command line option --version
may be used to change this
to 3.1.0
.
Programmatically, the method Generator::setVersion()
can be used to change the version.
Requirements
swagger-php
requires at least PHP 7.2 for annotations and PHP 8.1 for using attributes.
Installation (with Composer)
composer require zircote/swagger-php
For cli usage from anywhere install swagger-php globally and make sure to place the ~/.composer/vendor/bin
directory in your PATH so the openapi
executable can be located by your system.
composer global require zircote/swagger-php
doctrine/annotations
As of version 4.8
the doctrine annotations library is optional and no longer installed by default.
To use PHPDoc annotations this needs to be installed on top of swagger-php
:
composer require doctrine/annotations
If your code uses PHPDoc annotations you will need to install this as well:
composer require doctrine/annotations
Usage
Add annotations to your php files.
/** * @OA\Info(title="My First API", version="0.1") */ /** * @OA\Get( * path="/api/resource.json", * @OA\Response(response="200", description="An example resource") * ) */
Visit the Documentation website for the Getting started guide or look at the Examples directory for more examples.
Usage from php
Generate always-up-to-date documentation.
<?php require("vendor/autoload.php"); $openapi = \OpenApi\Generator::scan(['/path/to/project']); header('Content-Type: application/x-yaml'); echo $openapi->toYaml();
Documentation of how to use the Generator
class can be found in the Generator 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
Starting with version 4 the default analyser used on the command line is the new ReflectionAnalyser
.
Using the --legacy
flag (-l
) the legacy TokenAnalyser
can still be used.
Usage from the Deserializer
Generate the OpenApi annotation object from a json string, which makes it easier to manipulate objects programmatically.
<?php use OpenApi\Serializer; $serializer = new Serializer(); $openapi = $serializer->deserialize($jsonString, 'OpenApi\Annotations\OpenApi'); echo $openapi->toJson();