Feel free to connect with me by email or in Telegram.
Usage example on GitHub Gist
Bundle provides possibility for validate data according to the Swagger 2 documentation. You describe your API documentation by Swagger 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 Warmers mechanism.
In debug mode, the cache automatically warms up if you change the file containing the description of the documentation.
Note: as result bundle returns SwaggerResolver object - extension for the
OptionsResolver.
In this way you get full control over created resolver.
Attention: remember, when you change generated SwaggerResolver object you risk getting
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- scansrc/directory by default. Usesswagger_php.scanandswagger_php.excludeparameters.json- looking forweb/swagger.jsonby default. Usesconfiguration_fileparameter.
Open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle:
composer require adrenalinkin/swagger-resolver-bundleis command requires you to have Composer install globally.
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 bundle you don't need to define some additional configuration. All parameters have values by default:
# 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 excludedSwagger documentation preparation differ according to used tools of your project.
NelmioApiDocBundle
If your project has NelmioApiDocBundle connected, then no additional configuration is required.
swagger-php
In the absence of NelmioApiDocBundle, the bundle will degrade 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:
# 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
In the absence of NelmioApiDocBundle and swagger-php, the bundle will degrade to the configuration
loading by json file. In this case, by default, will be used web/swagger.json file.
Also, you can set custom path to the json configuration:
# app/config.yml
linkin_swagger_resolver:
configuration_file: '%kernel.project_dir%/web/swagger.json' # json extension is requiredYAML or (yml)
In the absence of NelmioApiDocBundle and swagger-php, but available
configuration file in the yaml or yml format you need to define path to that file:
# app/config.yml
linkin_swagger_resolver:
configuration_file: '%kernel.project_dir%/web/swagger.yaml' # yaml or yml extension is requiredCustom
If you need to use custom configuration loader you should implement custom loading process in the class, which implements SwaggerConfigurationLoaderInterface interface. After that you need to define name of that service in the configuration:
# 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));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.
Download the project:
git clone [email protected]:adrenalinkin/swagger-resolver-bundle.git
cd swagger-resolver-bundleFollow this instruction for set up simple docker container.
Install composer dependencies:
composer updateFor run the test suite:
bin/simple-phpunitFor run the PHP-CS-Fixer:
php-cs-fixer fix --diffFor run the composer-normalize:
composer-normalize --dry-run
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent