GitHub - zircote/swagger-php: A php swagger annotation and parsing library
source link: https://github.com/zircote/swagger-php
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
README.md
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 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") * ) */
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 = \OpenApi\scan('/path/to/project'); header('Content-Type: application/json'); echo $openapi;
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;
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
- 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
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK