en en en en en en en en en en en en en en en en en en en en en en en en nl en en en pt en ru en en en en en en en en de it en en en en en en en en en en en de en de de sv nn en en en en en en en en fr uk uk uk uk uk uk uk uk ru uk fr uk uk uk uk fr fr fr sv en en en en en en en en en en en en en en en en en en en en en en en en en en en en en en it en en en en da en en en en en en en en en en es en en en sv en en en en gu en en en en en id en en en
Bundle provides possibility for validate data according to the OpenApi 3 documentation. You describe your API documentation by OpenApi and provides verification of data for compliance with the described requirements. When documentation has been updated then verification will be updated too, all in one place!
Documentation is cached through the standard Symfony Cache mechanism.
Note: as result bundle returns OptionsResolver object. The object contains the created set of data requirements.
Attention: remember, when you change generated SwaggerResolver object you risk to get divergence with actual documentation.
Bundle provides integration with NelmioApiDocBundle, supports configuration loading by swagger-php and also supports loading directly from the json or yaml(yml) configuration file. When used default bundle configuration then swagger documentation will be load in most optimal available way. Loaders priority:
NelmioApiDocBundle - do not require any additional configuration.
swagger-php - Uses openapi_annotation.[area].scan and openapi_annotation.[area].exclude parameters.
json - Uses configuration_file.[area].file parameter.
Step 1: Download the Bundle
Open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle:
is command requires you to have Composer install globally.
Step 2: Enable the Bundle
Then, enable the bundle by updating your app/AppKernel.php file to enable the bundle:
<?php declare(strict_types=1); // app/AppKernel.php class AppKernel extends Kernel { // ... public function registerBundles() { $bundles = [ // ... new Linkin\Bundle\SwaggerResolverBundle\LinkinSwaggerResolverBundle(), ]; return $bundles; } // ... }
To start using the bundle, a preliminary configuration is required only in case of loading the configuration using swagger-php or a configuration file. Otherwise, no configuration is required.
# 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
Schema caching requires component configuration Symfony Cache.
# config/packages/cache.yaml framework: cache: pools: linkin_swagger_resolver.cache: adapter: cache.adapter.filesystem
Step 1: Swagger documentation preparation
OpenApi documentation preparation differ according to used tools of your project.
If your project has NelmioApiDocBundle connected, then no additional configuration is required.
In the absence of NelmioApiDocBundle, the bundle will degrades to the configuration loading by swagger-php annotations. In this case, by default, will be used src/ directory to scan. To optimize scanning process you can describe directories in the configuration:
# 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'
If NelmioApiDocBundle is missing, the bundle must be configured to load the json/yaml/yml file.
# config/packages/linkin_swagger_resolver.yaml linkin_swagger_resolver: configuration_file: default: file: '%kernel.project_dir%/web/swagger.json'
If you need to use your own loader, you need to replace the linkin_swagger_resolver.openapi_configuration_factory factory in the symfony container with your own.
Step 2: Data validation
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));
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 validates the data through the validator system. List of all validators, you can find out by going to the Validator folder. All validators registered as tagging services. To create your own validator it is enough to create class, which implements SwaggerValidatorInterface and then register it under the tag linkin_swagger_resolver.validator.
Bundle validates the data through the normalizer system. List of all normalizers, you can find out by going to the Normalizer folder. All normalizers registered as tagging services. To create your own normalizer it is enough to create class, which implements SwaggerNormalizerInterface and then register it under the tag linkin_swagger_resolver.normalizer.
The bundle provides the ability to use validators for the request body from the Symfony Validator package. To apply validation to a property, you need to add the required constraint to the annotation. Example for NotBlank, Email, NotCompromisedPassword, Length.
email; } public function getPassword(): string { return $this->email; } }
The bundle provides the ability to use enumerations for the request body from the marfatech/enumer-bundle package. To apply enums to a property, you need to add a class with a list of possible values to the annotation. The enumer class structure can be found in the documentation for marfatech/enumer-bundle.