, (*1)
swagger-php
Generate interactive OpenAPI documentation for your RESTful API using doctrine annotations., (*2)
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., (*3)
composer global require sonrac/swagger-php-openapi
Usage
Add annotations to your php files., (*4)
/**
* @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., (*5)
Usage from php
Generate always-up-to-date documentation., (*6)
<?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., (*7)
./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., (*8)
<?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., (*9)
The documentation website resides within the gh-pages branch., (*10)
Make sure pull requests pass PHPUnit
and PHP_CodeSniffer (PSR-2) tests., (*11)
Running tests can be done with this command in the root of the project:, (*12)
./bin/phpunit
To run the phpcs tests on your local machine execute:, (*13)
./bin/phpcs -p --extensions=php --standard=PSR2 --error-severity=1 --warning-severity=0 ./src ./tests
To run both unittests and linting execute:, (*14)
composer test
, (*15)
Wallogit.com
