Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/spiral-packages/swagger-php
Swagger PHP integration package for Spiral Framework.
https://github.com/spiral-packages/swagger-php
Last synced: about 2 months ago
JSON representation
Swagger PHP integration package for Spiral Framework.
- Host: GitHub
- URL: https://github.com/spiral-packages/swagger-php
- Owner: spiral-packages
- License: mit
- Created: 2023-12-25T09:25:11.000Z (about 1 year ago)
- Default Branch: 1.x
- Last Pushed: 2024-02-27T16:17:23.000Z (10 months ago)
- Last Synced: 2024-11-08T14:19:08.399Z (about 2 months ago)
- Language: PHP
- Size: 465 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Swagger-php
[](https://packagist.org/packages/spiral-packages/swagger-php)
[](https://packagist.org/packages/spiral-packages/swagger-php)
[](https://github.com/spiral-packages/swagger-php/actions)
[](https://github.com/spiral-packages/swagger-php/actions)
[](https://codecov.io/gh/spiral-packages/swagger-php)
[](https://packagist.org/packages/spiral-packages/swagger-php)
[](https://shepherd.dev/github/spiral-packages/swagger-php)
[](https://shepherd.dev/github/spiral-packages/swagger-php)
[**zircote/swagger-php**](https://github.com/zircote/swagger-php) integration package for Spiral Framework.
## Requirements
Make sure that your server is configured with following PHP version and extensions:
- PHP 8.1+
- Spiral framework 3.5+
## Installation
You can install the package via composer:
```bash
composer require spiral-packages/swagger-php
```
To enable the package in your Spiral Framework application, you will need to add
the `Spiral\OpenApi\Bootloader\SwaggerBootloader` class to the list of bootloaders in your application:
```php
protected const LOAD = [
// ...
\Spiral\OpenApi\Bootloader\SwaggerBootloader::class,
];
```
> **Note**
> If you are using [`spiral-packages/discoverer`](https://github.com/spiral-packages/discoverer),
> you don't need to register bootloader by yourself.
## Configuration
The configuration file should be located at `app/config/swagger.php`, and it allows you to set options.
Here is an example of how the configuration file might look:
```php
use Spiral\OpenApi\Config\SwaggerConfig;
use Spiral\OpenApi\Generator\Parser\ConfigurationParser;
use Spiral\OpenApi\Generator\Parser\OpenApiParser;
use Spiral\OpenApi\Renderer\HtmlRenderer;
use Spiral\OpenApi\Renderer\JsonRenderer;
use Spiral\OpenApi\Renderer\YamlRenderer;
return [
'documentation' => [
'info' => [
'title' => 'My App',
'description' => 'API documentation',
'version' => '1.0.0',
],
],
'parsers' => [
ConfigurationParser::class,
OpenApiParser::class,
],
'renderers' => [
JsonRenderer::FORMAT => JsonRenderer::class,
YamlRenderer::FORMAT => YamlRenderer::class,
HtmlRenderer::FORMAT => HtmlRenderer::class,
],
'paths' => [
directory('app'),
],
'exclude' => null,
'pattern' => null,
'version' => null,
'cache_key' => SwaggerConfig::DEFAULT_CACHE_KEY,
'generator_config' => [
'operationId' => [
'hash' => true,
],
],
'use_cache' => env('APP_ENV') === 'prod',
];
```
## Usage
First, create an entity that represents the resource you want to document. For example, you can create
a **User** entity that represents a user resource:
```php
namespace App\Entity;
use OpenApi\Attributes as OA;
#[OA\Schema(
schema: 'User',
description: 'User record',
required: ['email', 'first_name', 'last_name'],
type: 'object',
)]
class User
{
#[OA\Property(type: 'string')]
public string $email;
#[OA\Property(property: 'first_name', type: 'string')]
public string $firstName;
#[OA\Property(property: 'last_name',type: 'string')]
public string $lastName;
}
```
Next, create a Controller that handles the actions for the resource, and add Swagger attributes to the actions
to describe the behavior of the endpoint. For example, you can create a **UserController** that handles the **list**
action for the User resource:
```php
use OpenApi\Attributes as OA;
use Psr\Http\Message\ResponseInterface;
class UserController
{
#[OA\Get(
path: '/api/v1/users',
tags: ['User'],
parameters: [
new OA\Parameter(ref: '#/components/parameters/page'),
new OA\Parameter(ref: '#/components/parameters/limit'),
new OA\Parameter(
name: 'sort',
description: 'The field used to order users',
in: 'query',
schema: new OA\Schema(type: 'string'),
examples: [
'user.first_name' => new OA\Examples(
example: 'user.first_name',
summary: 'Sort by `user.first_name` field',
value: 'user.first_name'
),
'user.last_name' => new OA\Examples(
example: 'user.last_name',
summary: 'Sort by `user.last_name` field',
value: 'user.last_name'
),
]
),
new OA\Parameter(ref: '#/components/parameters/direction')
],
responses: [
new OA\Response(
response: 200,
description: 'Retrieve a collection of users',
content: new OA\JsonContent(
properties: [
new OA\Property(
property: 'meta',
ref: '#/components/schemas/ResponseCollectionMeta'
),
new OA\Property(
property: 'data',
description: 'Collection of users',
type: 'array',
items: new OA\Items(type: 'array', items: new OA\Items(
properties: [
new OA\Property(
property: 'uuid',
type: 'string',
example: '7be33fd4-ff46-11ea-adc1-0242ac120002'
),
new OA\Property(
property: 'type',
type: 'string'
),
new OA\Property(
property: 'attributes',
ref: '#/components/schemas/User'
),
],
type: 'object'
))
),
],
type: 'object'
)
),
]
)]
public function list(): ResponseInterface
{
// ...
}
}
```
Some elements like **page**, **limit**, **direction** parameters. The **ResponseCollectionMeta** schema can be used
in a variety of places. Therefore, they can be defined in the configuration file:
```php
// file app/config/swagger.php
return [
'documentation' => [
'info' => [
'title' => 'My App',
'description' => 'My App API Documentation',
'version' => '1.0.0'
],
'components' => [
'parameters' => [
'page' => [
'name' => 'page',
'in' => 'query',
'example' => 1,
'schema' => [
'type' => 'integer'
]
],
'limit' => [
'name' => 'limit',
'in' => 'query',
'example' => 25,
'schema' => [
'type' => 'integer'
]
],
'direction' => [
'name' => 'direction',
'in' => 'query',
'schema' => [
'type' => 'string'
],
'examples' => [
'asc' => [
'value' => 'asc',
'summary' => 'Sort Ascending'
],
'desc' => [
'value' => 'desc',
'summary' => 'Sort Descending'
]
]
]
],
'schemas' => [
'ResponseCollectionMeta' => [
'type' => 'object',
'properties' => [
'size' => [
'type' => 'integer'
],
'page' => [
'type' => 'integer'
],
'total' => [
'type' => 'integer'
]
]
]
]
]
],
];
```
The package provides a `Spiral\OpenApi\Controller\DocumentationController` controller that can render
the documentation in various formats such as HTML, JSON, and YAML. The HTML format uses the `Swagger UI` for displaying
the documentation. To use this controller, it is necessary to add a route
in the `App\Application\Bootloader\RoutesBootloader` file:
```php
use Spiral\OpenApi\Controller\DocumentationController;
final class RoutesBootloader extends BaseRoutesBootloader
{
protected function defineRoutes(RoutingConfigurator $routes): void
{
// ...
$routes
->add('swagger-api-html', '/api/docs')
->action(DocumentationController::class, 'html');
$routes
->add('swagger-api-json', '/api/docs.json')
->action(DocumentationController::class, 'json');
$routes
->add('swagger-api-yaml', '/api/docs.yaml')
->action(DocumentationController::class, 'yaml');
// ...
}
}
```
## Testing
```bash
composer test
```
```bash
composer psalm
```
```bash
composer cs
```
## License
The MIT License (MIT). Please see [License File](LICENSE) for more information.