zircote/swagger-php

swagger-php - Generate interactive documentation for your RESTful API using phpdoc annotations

Friday, June 29, 2018
by bfanger
Repository
103 Watchers
2143 Stars
4,040,394 Installations

PHP
117 Dependents
5 Suggesters
448 Forks
66 Open issues
45 Versions
16 % Grown

The README.md

, _(*1)

swagger-php

Generate interactive OpenAPI documentation for your RESTful API using PHP attributes (preferred) or doctrine annotations (requires additional doctrine/annotations library)., _(*2)

See the documentation website for supported attributes and annotations., _(*3)

Annotations are deprecated and may be removed in a future release of swagger-php., _(*4)

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., _(*5)

Programmatically, the method Generator::setVersion() can be used to change the version., _(*6)

Requirements

swagger-php requires at least PHP 7.2 for annotations and PHP 8.1 for using attributes., _(*7)

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., _(*8)

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., _(*9)

To use PHPDoc annotations this needs to be installed on top of swagger-php:, _(*10)

composer require doctrine/annotations

If your code uses PHPDoc annotations you will need to install this as well:, _(*11)

composer require doctrine/annotations

Usage

Add annotations to your php files., _(*12)

/**
 * @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., _(*13)

Usage from php

Generate always-up-to-date documentation., _(*14)

<?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., _(*15)

Usage from the Command Line Interface

The openapi command line interface can be used to generate the documentation to a static yaml/json file., _(*16)

./vendor/bin/openapi --help

Starting with version 4 the default analyser used on the command line is the new ReflectionAnalyser., _(*17)

Using the --legacy flag (-l) the legacy TokenAnalyser can still be used., _(*18)

Usage from the Deserializer

Generate the OpenApi annotation object from a json string, which makes it easier to manipulate objects programmatically., _(*19)

<?php

use OpenApi\Serializer;

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

Contributing

More on OpenApi & Swagger

https://swagger.io
https://www.openapis.org
OpenApi Documentation
OpenApi Specification
Related projects

The Versions

29/06 2018

3.x-dev

3.9999999.9999999.9999999-dev https://github.com/zircote/swagger-php/

swagger-php - Generate interactive documentation for your RESTful API using phpdoc annotations

library swagger-php

swagger-php - Generate interactive documentation for your RESTful API using phpdoc annotations

zircote/swagger-php

The README.md

swagger-php

Features

OpenAPI version support

Requirements

Installation (with Composer)

doctrine/annotations

Usage

Usage from php

Usage from the Command Line Interface

Usage from the Deserializer

Contributing

More on OpenApi & Swagger

The Versions

3.x-dev

The Requires

The Development Requires

by Robert Allen

by Bob Fanger

dev-master

The Requires

The Development Requires

by Robert Allen

by Bob Fanger

2.x-dev

The Requires

The Development Requires

by Robert Allen

by Bob Fanger

dev-related-projects

The Requires

The Development Requires

by Robert Allen

by Bob Fanger

2.0.13

The Requires

The Development Requires

by Robert Allen

by Bob Fanger

dev-example-dynamic-references

The Requires

The Development Requires

by Robert Allen

by Bob Fanger

2.0.12

The Requires

The Development Requires

by Robert Allen

by Bob Fanger

2.0.11

The Requires

The Development Requires

by Robert Allen

by Bob Fanger

dev-testrun

The Requires

The Development Requires

by Robert Allen

by Bob Fanger

2.0.10

The Requires

The Development Requires

by Robert Allen

by Bob Fanger

2.0.9

The Requires

The Development Requires

by Robert Allen

by Bob Fanger

2.0.8

The Requires

The Development Requires

by Robert Allen

by Bob Fanger

2.0.7

The Requires

The Development Requires