You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Martin Rademacher 46c3e4c493
Dev tools (#1243)
1 day ago
.github/workflows Docs codeblocks (#1232) 3 days ago
Examples Components cleanup (#1199) 4 weeks ago
bin OpenApi version override (#1179) 2 months ago
docs Dev tools (#1243) 1 day ago
src Dev tools (#1243) 1 day ago
tests Allow original backing value in Enum (#1239) 3 days ago
tools Dev tools (#1243) 1 day ago
.editorconfig Dev tools (#1243) 1 day ago
.gitattributes Dev tools (#1243) 1 day ago
.gitignore Add test to ensure attribute parameters are matching annotations (#1217) 3 weeks ago
.php-cs-fixer.dist.php Dev tools (#1243) 1 day ago
.spectral.yaml Improve example specs (#990) 8 months ago
Changelog.md Document the changelog on the github releases page 4 years ago
LICENSE Rename license file to be in line with what GH expects (#1188) 2 months ago
README.md Docs codeblocks (#1232) 3 days ago
composer.json Dev tools (#1243) 1 day ago
phpstan-baseline.neon Add PHPStan workflow and baseline (#1222) 3 weeks ago
phpstan.neon Add PHPStan workflow and baseline (#1222) 3 weeks ago
phpunit.xml.dist Github action CI migration (#886) 1 year ago
psalm-baseline.xml Add Psalm to analysis chain (#1223) 3 weeks ago
psalm.xml Add Psalm to analysis chain (#1223) 3 weeks ago

README.md

Build Status
Total Downloads
License

swagger-php

Generate interactive OpenAPI documentation for your RESTful API using doctrine annotations.

For a full list of supported annotations, please have look at the OpenApi\Annotations namespace or the documentation website.

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

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();

Usage from docker

Generate the swagger documentation to a static json file.

docker run -v "$PWD":/app -it tico/swagger-php --help

More on OpenApi & Swagger

Contributing

Feel free to submit Github Issues
or pull requests.

The documentation website is build from the docs folder with vuepress.

Make sure pull requests pass PHPUnit
and PHP-CS-Fixer (PSR-2) tests.

To run both unit tests and linting execute:

composer test

Running unit tests only:

./bin/phpunit

Regenerate annotation/attribute reference markup docs

composer docs:refgen

Running linting only:

composer lint

To make php-cs-fixer fix linting errors:

composer cs