sonrac/swagger-php-openapi

Swagger-PHP - Generate interactive documentation for your RESTful API using phpdoc annotations

3.0.0 2018-06-06 11:45 UTC

Requires

• php: >=7.0
• doctrine/annotations: *
• symfony/finder: *

Requires (Dev)

• phpunit/phpunit: >=6.3
• squizlabs/php_codesniffer: >=2.7
• zendframework/zend-form: <2.8

Apache-2.0

• Robert Allen
• Bob Fanger

• json
• rest
• api
• service discovery

README

swagger-php

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

Features

• Compatible with the OpenAPI 3.0 specification.
• Exceptional error reporting (with hints, context)
• Extracts information from code & existing phpdoc annotations.
• Command-line interface available.

Installation (with Composer)

composer require sonrac/swagger-php-openapi

For cli usage from anywhere install swagger-php globally and make sure to place the ~/.composer/vendor/bin directory in your PATH so the swagger executable can be located by your system.

composer global require sonrac/swagger-php-openapi

Usage

Add annotations to your php files.

/**
 * @OAS\Info(title="My First API", version="0.1")
 */

/**
 * @OAS\Get(
 *     path="/api/resource.json",
 *     @OAS\Response(response="200", description="An example resource")
 * )
 */

See the Getting started guide and Examples directory for more examples.

Usage from php

Generate always-up-to-date documentation.

<?php
require("vendor/autoload.php");
$openapi = \Swagger\scan('/path/to/project');
header('Content-Type: application/json');
echo $openapi;

Usage from the Command Line Interface

Generate the swagger documentation to a static json file.

./vendor/bin/swagger --help

Usage from the Deserializer

Generate the OpenApi annotation object from a json string, which makes it easier to manipulate objects programmatically.

<?php

use Swagger\Serializer;

$serializer = new Serializer();
$openapi = $serializer->deserialize($jsonString, 'Swagger\Annotations\OpenApi');
echo $openapi;

More on OpenAPI

• https://www.openapis.org
• https://github.com/swagger-api/swagger-spec/
• http://bfanger.github.io/swagger-explained/
• Related projects
• https://www.marcoraddatz.com/en/2015/07/21/integrate-swagger-into-laravel/

Contributing

Feel free to submit Github Issues or pull requests.

The documentation website resides within the gh-pages branch.

Make sure pull requests pass PHPUnit and PHP_CodeSniffer (PSR-2) tests.

Running tests can be done with this command in the root of the project:

./bin/phpunit

To run the phpcs tests on your local machine execute:

./bin/phpcs -p --extensions=php --standard=PSR2 --error-severity=1 --warning-severity=0 ./src ./tests

To run both unittests and linting execute:

composer test