README

zircote/swagger-php 是用于 Spiral 框架的集成包。

要求

确保您的服务器已配置以下 PHP 版本和扩展

• PHP 8.1+
• Spiral 框架 3.5+

安装

您可以通过 composer 安装此包

composer require spiral-packages/swagger-php

要启用 Spiral 框架应用程序中的包，您需要将 Spiral\OpenApi\Bootloader\SwaggerBootloader 类添加到应用程序的引导加载器列表中

protected const LOAD = [
    // ...
    \Spiral\OpenApi\Bootloader\SwaggerBootloader::class,
];

注意 如果您正在使用 spiral-packages/discoverer，则无需自行注册引导加载器。

配置

配置文件应位于 app/config/swagger.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',
];

用法

首先，创建一个表示您想要记录的资源实体。例如，您可以创建一个表示用户资源的 User 实体

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;
}

接下来，创建一个处理资源操作的 Controller，并在操作中添加 Swagger 属性以描述端点的行为。例如，您可以创建一个处理用户资源 list 操作的 UserController

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
    {
        // ...
    }
}

一些元素如 page、limit、direction 参数。可以在多个地方使用 ResponseCollectionMeta 架构。因此，它们可以在配置文件中定义

// 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'
                        ]
                    ]
                ]
            ]
        ]
    ],
];

该包提供了一个 Spiral\OpenApi\Controller\DocumentationController 控制器，可以以各种格式渲染文档，如 HTML、JSON 和 YAML。HTML 格式使用 Swagger UI 显示文档。要使用此控制器，需要在 App\Application\Bootloader\RoutesBootloader 文件中添加一个路由

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');

       // ...
    }
}

测试

composer test

composer psalm

composer cs

许可

MIT 许可证 (MIT)。请参阅 许可文件 了解更多信息。