yiisoft / yii-swagger
OpenAPI Swagger for Yii Framework
Fund package maintenance!
Opencollective
yiisoft
Installs: 60 560
Dependents: 6
Suggesters: 0
Security: 0
Stars: 24
Watchers: 16
Forks: 4
Open Issues: 3
Requires
- php: ^8.0
- psr/http-message: ^1.0
- psr/http-server-handler: ^1.0
- psr/http-server-middleware: ^1.0
- swagger-api/swagger-ui: ^4.1
- yiisoft/aliases: ^1.1|^2.0|^3.0
- yiisoft/arrays: ^3.0
- yiisoft/assets: ^2.0|^3.0|^4.0
- yiisoft/cache: ^1.0|^2.0|^3.0
- yiisoft/data-response: ^1.0|^2.0
- yiisoft/html: ^3.0
- yiisoft/yii-view: ^4.0|^5.0|^6.0
- zircote/swagger-php: ^4.0
Requires (Dev)
- httpsoft/http-message: ^1.0
- maglnet/composer-require-checker: ^4.4
- phpunit/phpunit: ^9.5
- rector/rector: ^0.15.3
- roave/infection-static-analysis-plugin: ^1.16
- spatie/phpunit-watcher: ^1.23
- vimeo/psalm: ^4.30|^5.6
- yiisoft/csrf: ^2.0
- yiisoft/di: ^1.2
- yiisoft/psr-dummy-provider: ^1.0
- yiisoft/test-support: ^3.0
README
Yii Swagger
OpenAPI Swagger for Yii Framework.
Requirements
- PHP 8.0 or higher.
Installation
The package could be installed with composer:
composer require yiisoft/yii-swagger
Configuration
1. Add route configuration to config/routes.php
use Yiisoft\DataResponse\Middleware\FormatDataResponseAsHtml; use Yiisoft\DataResponse\Middleware\FormatDataResponseAsJson; use Yiisoft\Router\Group; use Yiisoft\Router\Route; use Yiisoft\Swagger\Middleware\SwaggerUi; use Yiisoft\Swagger\Action\SwaggerJson; // Swagger routes Group::create('/swagger', [ Route::get('') ->middleware(FormatDataResponseAsHtml::class) ->action(fn (SwaggerUi $swaggerUi) => $swaggerUi->withJsonUrl('/swagger/json-url')), Route::get('/json-url') ->middleware(FormatDataResponseAsJson::class) ->action(SwaggerJson::class), ]),
2. Add annotations to default API controller
use OpenApi\Annotations as OA; /** * @OA\Info(title="My first API", version="1.0") */ class DefaultController { // ... }
and before actions
/** * @OA\Get( * path="/api/endpoint", * @OA\Response(response="200", description="Get default action") * ) */ public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface { // ... }
See Swagger-PHP documentation for details on how to annotate your code.
3. Configure SwaggerJson
action
For annotations to be registered you need to configure SwaggerJson
.
You can use the parameters in config/params.php
to configure SwaggerJson
:
//... 'yiisoft/yii-swagger' => [ 'annotation-paths' => [ '@src/Controller' // Directory where annotations are used ], 'cacheTTL' => 60 // Enables caching and sets TTL, "null" value means infinite cache TTL. ], //...
4. (Optional) Add config for aliases and asset manager
use Yiisoft\Definitions\Reference; use Yiisoft\Assets\AssetManager; return [ //... 'yiisoft/aliases' => [ 'aliases' => [ //... '@views' => '@root/views', '@assets' => '@public/assets', '@assetsUrl' => '@baseUrl/assets', ], ], 'yiisoft/view' => [ 'basePath' => '@views', 'defaultParameters' => [ 'assetManager' => Reference::to(AssetManager::class), ] ], //... ];
5. (Optional) Configure SwaggerUi
action
You can use the parameters in config/params.php
to configure SwaggerUi
.
For example, you can enable persisting authorization by setting the persistAuthorization
parameter to true
.
//... 'yiisoft/yii-swagger' => [ 'ui-params' => [ 'persistAuthorization' => true, ], ], //...
You can find a complete list of parameters by following the link.
6. (Optional) Configure SwaggerService
You can specify options for generation an OpenApi\Annotations\OpenApi
instance in config/params.php
to configure SwaggerService
:
//... 'yiisoft/yii-swagger' => [ // Default values are specified. 'open-api-options' => [ 'aliases' => OpenApi\Generator::DEFAULT_ALIASES, 'namespaces' => OpenApi\Generator::DEFAULT_NAMESPACES, 'analyser' => null, 'analysis' => null, 'processors' => null, 'logger' => null, 'validate' => true, 'version' => OpenApi\Annotations\OpenApi::DEFAULT_VERSION, ], ], //...
For more information about generation an OpenApi\Annotations\OpenApi
instance, see the
documentation of the zircote/swagger-php package.
Testing
Unit testing
The package is tested with PHPUnit. To run tests:
./vendor/bin/phpunit
Mutation testing
The package tests are checked with Infection mutation framework with Infection Static Analysis Plugin. To run it:
./vendor/bin/roave-infection-static-analysis-plugin
Static analysis
The code is statically analyzed with Psalm. To run static analysis:
./vendor/bin/psalm
License
The Yii Swagger is free software. It is released under the terms of the BSD License.
Please see LICENSE
for more information.
Maintained by Yii Software.