yiisoft / yii-swagger
OpenAPI Swagger for Yii Framework
Fund package maintenance!
Opencollective
yiisoft
Installs: 86 657
Dependents: 5
Suggesters: 0
Security: 0
Stars: 30
Watchers: 18
Forks: 8
Open Issues: 4
Requires
- php: ^8.0
- psr/http-message: ^1.0|^2.0
- psr/http-server-handler: ^1.0
- psr/http-server-middleware: ^1.0
- swagger-api/swagger-ui: ^4.1|^5.0
- 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-renderer: ^7.1.0
- zircote/swagger-php: ^4.0
Requires (Dev)
- doctrine/annotations: ^2.0
- httpsoft/http-message: ^1.0
- maglnet/composer-require-checker: ^4.4
- phpunit/phpunit: ^9.5
- rector/rector: ^1.0
- 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.
Documentation
If you need help or have a question, the Yii Forum is a good place for that. You may also check out other Yii Community Resources.
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.