README

您可以通过电子邮件或在Telegram与我联系。

在GitHub Gist上的使用示例

简介

此Bundle提供根据Swagger 2文档验证数据的功能。您通过Swagger描述您的API文档，并验证数据是否符合描述的要求。当文档更新时，验证也会更新，所有操作都在一个地方完成！

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

注意：作为结果，此Bundle返回SwaggerResolver对象 - OptionsResolver的扩展。这样，您可以完全控制创建的解析器。

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

集成

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

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

安装

步骤1：下载Bundle

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

    composer require adrenalinkin/swagger-resolver-bundle

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

步骤2：启用Bundle

然后，通过更新您的app/AppKernel.php文件以启用Bundle来启用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，您不需要定义任何额外的配置。所有参数都有默认值

# 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，则此Bundle将降级到通过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

第二步：数据验证

模型验证

<?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。

运行测试和静态分析工具

下载项目

git clone git@github.com:adrenalinkin/swagger-resolver-bundle.git
cd swagger-resolver-bundle

按照此 说明 设置简单的 Docker 容器。

安装 composer 依赖

composer update

运行测试套件

bin/simple-phpunit

运行 PHP-CS-Fixer

php-cs-fixer fix --diff

运行 composer-normalize

composer-normalize --dry-run

许可协议