README

警告：此仓库不再积极维护

介绍

此包提供根据Swagger 2文档验证数据的功能。您通过Swagger描述您的API文档，并提供验证数据以符合所述要求。当文档更新时，验证也将更新，一切都在一个地方完成！

文档通过标准Symfony Warmers机制进行缓存。在调试模式下，如果更改包含文档描述的文件，缓存将自动预热。

注意：结果包返回SwaggerResolver对象——OptionsResolver的扩展。这样您可以完全控制创建的解析器。

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

集成

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

1. NelmioApiDocBundle - 不需要任何额外的配置。
2. swagger-php - 默认扫描src/目录。使用swagger_php.scan和swagger_php.exclude参数。
3. json - 默认查找web/swagger.json。使用configuration_file参数。

安装

步骤1：下载包

打开命令行，进入您的项目目录，并执行以下命令以下载此包的最新稳定版本

    composer require adrenalinkin/swagger-resolver-bundle

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

步骤2：启用包

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

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

class AppKernel extends Kernel
{
    // ...

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

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

        return $bundles;
    }

    // ...
}

配置

要开始使用此包，您不需要定义任何额外的配置。所有参数都有默认值

# app/config.yml
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\Bundle\SwaggerResolverBundle\Merger\Strategy\StrictMergeStrategy
    configuration_loader_service:   ~   # the name of the configuration loader service
    configuration_file:             ~   # full path to the configuration file
    swagger_php:                        # settings for the swagger-php
        scan:       ~                   # array of the full paths for the annotations scan
        exclude:    ~                   # array of the full paths which should be excluded

使用方法

步骤1：准备Swagger文档

Swagger文档的准备根据您的项目所使用的工具而有所不同。

NelmioApiDocBundle

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

swagger-php

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

# app/config.yml
linkin_swagger_resolver:
    swagger_php:
        scan:
            - '%kernel.project_dir%/src/Acme/ApiBundle'
        exclude:
            - '%kernel.project_dir%/src/Acme/ApiBundle/Resources'
            - '%kernel.project_dir%/src/Acme/ApiBundle/Repository'

JSON

如果没有 NelmioApiDocBundle 和 swagger-php，则该组件将降级为通过 json 文件加载配置。在这种情况下，默认情况下将使用 web/swagger.json 文件。您还可以设置自定义的 json 配置路径。

# app/config.yml
linkin_swagger_resolver:
    configuration_file: '%kernel.project_dir%/web/swagger.json' # json extension is required

YAML 或 (yml)

如果没有 NelmioApiDocBundle 和 swagger-php，但有以 yaml 或 yml 格式的配置文件，则需要定义该文件的路径。

# app/config.yml
linkin_swagger_resolver:
    configuration_file: '%kernel.project_dir%/web/swagger.yaml' # yaml or yml extension is required

自定义

如果您需要使用自定义配置加载器，则应在实现 SwaggerConfigurationLoaderInterface 接口的自定义类中实现自定义加载过程。之后，您需要在配置中定义该服务的名称。

# app/config.yml
linkin_swagger_resolver:
    configuration_loader_service: acme_app.custom_configuration_loader

第 2 步：数据验证

模型验证

<?php declare(strict_types=1);

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

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

请求验证

<?php declare(strict_types=1);

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

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

高级

自定义验证器

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

自定义标准化器

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

许可证