README

简介

Bundle 提供了根据 OpenApi 3 文档验证数据的能力。您通过 OpenApi 描述您的 API 文档，并验证数据是否符合描述的要求。当文档更新时，验证也会更新，一切都在一个地方完成！

文档通过标准 Symfony 缓存 机制进行缓存。

注意：作为结果，bundle 返回 OptionsResolver 对象。该对象包含创建的数据要求集。

注意：请记住，当您更改生成的 SwaggerResolver 对象时，您可能会与实际文档出现偏差。

集成

Bundle 提供与 NelmioApiDocBundle 的集成，支持通过 swagger-php 加载配置，同时也支持直接从 json 或 yaml(yml) 配置文件加载。当使用默认的 bundle 配置时，swagger 文档将以最优化方式加载。加载器优先级

1. NelmioApiDocBundle - 不需要任何额外配置。
2. swagger-php - 使用 openapi_annotation.[area].scan 和 openapi_annotation.[area].exclude 参数。
3. json - 使用 configuration_file.[area].file 参数。

安装

步骤 1: 下载 Bundle

打开命令行，进入您的项目目录，然后执行以下命令以下载该 bundle 的最新稳定版本

    composer require marfatech/swagger-resolver-bundle

此命令要求您全局安装 Composer。

步骤 2: 启用 Bundle

然后，通过更新您的 app/AppKernel.php 文件来启用该 bundle

<?php declare(strict_types=1);
// app/AppKernel.php

class AppKernel extends Kernel
{
    // ...

    public function registerBundles()
    {
        $bundles = [
            // ...

            new Linkin\Bundle\SwaggerResolverBundle\LinkinSwaggerResolverBundle(),
        ];

        return $bundles;
    }

    // ...
}

配置

要开始使用该 bundle，如果使用 swagger-php 或配置文件加载配置，则需要先进行初步配置。否则，无需配置。

# config/packages/linkin_swagger_resolver.yaml
linkin_swagger_resolver:
    # default parameter locations which can apply normalization
    enable_normalization:
        - 'query'
        - 'path'
        - 'header'
    # strategy for merge all request parameters.
    path_merge_strategy:                linkin_swagger_resolver.merge_strategy.strict
    configuration_file:
        default:                        # api area
            file:       ~               # full path to the configuration file
    openapi_annotation:                 # settings for the swagger-php
        default:                        # api area
            scan:       ~               # array of the full paths for the annotations scan
            exclude:    ~               # array of the full paths which should be excluded

模式缓存需要组件配置 Symfony Cache。

# config/packages/cache.yaml
framework:
    cache:
        pools:
            linkin_swagger_resolver.cache:
                adapter: cache.adapter.filesystem

使用方法

步骤 1: Swagger 文档准备

OpenApi 文档的准备工作取决于您项目中使用的工具。

NelmioApiDocBundle

如果您的项目已连接 NelmioApiDocBundle，则无需任何额外配置。

swagger-php

如果没有 NelmioApiDocBundle，该 bundle 将降级到通过 swagger-php 注解加载配置。在这种情况下，默认情况下将使用 src/ 目录进行扫描。为了优化扫描过程，您可以在配置中描述目录

# config/packages/linkin_swagger_resolver.yaml
linkin_swagger_resolver:
    openapi_annotation:
        default:
            scan:
                - '%kernel.project_dir%/src/Acme/ApiBundle'
            exclude:
                - '%kernel.project_dir%/src/Acme/ApiBundle/Resources'
                - '%kernel.project_dir%/src/Acme/ApiBundle/Repository'

JSON/YAML 或 (yml)

如果没有 NelmioApiDocBundle，则必须配置 bundle 以加载 json/yaml/yml 文件。

# config/packages/linkin_swagger_resolver.yaml
linkin_swagger_resolver:
    configuration_file:
        default:
            file: '%kernel.project_dir%/web/swagger.json'

自定义

如果您需要使用自己的加载器，则需要替换 symfony 容器中的 linkin_swagger_resolver.openapi_configuration_factory 工厂为您的自定义工厂。

步骤 2: 数据验证

模型验证

<?php declare(strict_types=1);

/** @var \Linkin\Bundle\SwaggerResolverBundle\Factory\OpenApiResolverFactory $factory */
$factory = $container->get('linkin_swagger_resolver.openapi_resolver_factory');
// loading by fully qualified class name
$optionsResolver = $factory->createForSchema(AcmeApiModel::class);
// loading by class name
$optionsResolver = $factory->createForSchema('AcmeApiModel');

/** @var \Symfony\Component\HttpFoundation\Request $request */
$data = $optionsResolver->resolve(json_decode($request->getContent(), true));

请求验证

<?php declare(strict_types=1);

/** @var \Linkin\Bundle\SwaggerResolverBundle\Factory\OpenApiResolverFactory $factory */
$factory = $container->get('linkin_swagger_resolver.openapi_resolver_factory');
$request = $container->get('request_stack')->getCurrentRequest();
// Loading by request
$optionsResolver = $factory->createForRequest($request);

$data = $optionsResolver->resolve(json_decode($request->getContent(), true));

高级

自定义验证器

Bundle通过验证器系统验证数据。所有验证器的列表，您可以通过访问验证器文件夹找到。所有验证器都注册为标记服务。要创建自己的验证器，只需创建一个实现SwaggerValidatorInterface的类，然后将其注册在标记linkin_swagger_resolver.validator下。

自定义规范化器

Bundle通过规范化器系统验证数据。所有规范化器的列表，您可以通过访问规范化器文件夹找到。所有规范化器都注册为标记服务。要创建自己的规范化器，只需创建一个实现SwaggerNormalizerInterface的类，然后将其注册在标记linkin_swagger_resolver.normalizer下。

Symfony验证器

该Bundle提供了使用来自Symfony Validator包的请求体验证器的功能。要将验证应用于属性，您需要将所需的约束添加到注解中。例如，对于NotBlank、Email、NotCompromisedPassword、Length。

<?php

declare(strict_types=1);

namespace Acme\Dto;

use OpenApi\Annotations as OA;
use Symfony\Component\Validator\Constraints as Assert;

/**
 * @OA\Schema(
 *     type="object",
 *     description="Entry DTO for create user endpoint",
 *     required={
 *         "email",
 *         "password",
 *     },
 * )
 */
class UserEntryDto
{
    /**
     * @Assert\NotBlank(message="You should fill email")
     * @Assert\Email()
     *
     * @OA\Property(
     *     example="[email protected]",
     * )
     */
    private string $email;
    
    /**
     * @Assert\NotCompromisedPassword()
     * @Assert\Length(min=8, max=24)
     *
     * @OA\Property(
     *     example="qwerty123",
     * ) 
     */
    private string $password;
    
    public  function getEmail(): string
    {
        return $this->email;
    }
    
    public  function getPassword(): string
    {
        return $this->email;
    }
}

枚举的使用

该Bundle提供了使用来自marfatech/enumer-bundle包的请求体枚举的功能。要将枚举应用于属性，您需要将包含可能值的类添加到注解中。枚举类结构可以在marfatech/enumer-bundle的文档中找到。

<?php

declare(strict_types=1);

namespace Acme\Dto;

use Acme\Enum\UserStatusEnum;
use OpenApi\Annotations as OA;
use Symfony\Component\Validator\Constraints as Assert;
use MarfaTech\Bundle\EnumerBundle\Enum\EnumInterface;

/**
 * @OA\Schema(
 *     type="object",
 *     description="Entry DTO for change status user endpoint",
 *     required={
 *         "status",
 *     },
 * )
 */
class UserStatusEntryDto
{
    /**
     * @OA\Property(
     *     enum=UserStatusEnum::class,
     *     example=UserStatusEnum::ACTIVE,
     * )
     */
    private string $status;
    
    public  function getStatus(): string
    {
        return $this->status;
    }
}

许可证