Skip to content
Branch: master
Go to file
Code

Latest commit

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
bin
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Build Status Total Downloads License

swagger-php

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

Features

  • Compatible with the OpenAPI 3.0 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)

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\scan('/path/to/project');
header('Content-Type: application/x-yaml');
echo $openapi->toYaml();

Usage from the Command Line Interface

Generate the documentation to a static json file.

./vendor/bin/openapi --help

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_CodeSniffer (PSR-2) tests.

To run both unittests and linting execute:

composer test

Running only unittests:

./bin/phpunit

Running only linting:

./bin/phpcs -p --extensions=php --standard=PSR2 --error-severity=1 --warning-severity=0 ./src ./tests
You can’t perform that action at this time.