yii2mod / yii2-swagger
Swagger Documentation Generator for Yii2 Framework
Installs: 291 393
Dependents: 8
Suggesters: 0
Security: 0
Stars: 63
Watchers: 5
Forks: 32
Open Issues: 13
Type:yii2-extension
Requires
- php: >=7.1.0
- bower-asset/swagger-ui: ^3.1
- yiisoft/yii2: ~2.0.12
- zircote/swagger-php: ^2.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ~2.0
- phpunit/phpunit: ~6.0
This package is not auto-updated.
Last update: 2024-10-27 05:36:08 UTC
README
Swagger Documentation Generator for Yii2 Framework
Swagger/OpenAPI Documentation Generator for Yii2 Framework.
Installation
The preferred way to install this extension is through composer.
Either run
php composer.phar require --prefer-dist yii2mod/yii2-swagger "*"
or add
"yii2mod/yii2-swagger": "*"
to the require section of your composer.json.
Configuration
You need to configure two actions as follows:
<?php namespace app\controllers; use Yii; use yii\helpers\Url; use yii\web\Controller; /** * @SWG\Swagger( * basePath="/", * produces={"application/json"}, * consumes={"application/x-www-form-urlencoded"}, * @SWG\Info(version="1.0", title="Simple API"), * ) */ class SiteController extends Controller { /** * @inheritdoc */ public function actions(): array { return [ 'docs' => [ 'class' => 'yii2mod\swagger\SwaggerUIRenderer', 'restUrl' => Url::to(['site/json-schema']), ], 'json-schema' => [ 'class' => 'yii2mod\swagger\OpenAPIRenderer', // Тhe list of directories that contains the swagger annotations. 'scanDir' => [ Yii::getAlias('@app/controllers'), Yii::getAlias('@app/models'), ], ], 'error' => [ 'class' => 'yii\web\ErrorAction', ], ]; } }
Usage
- Creating a Controller
First, create a controller class app\controllers\UserController
as follows:
namespace app\controllers; use app\models\User; use yii\data\ActiveDataProvider; use yii\rest\Controller; /** * Class UserController */ class UserController extends Controller { /** * @SWG\Get(path="/user", * tags={"User"}, * summary="Retrieves the collection of User resources.", * @SWG\Response( * response = 200, * description = "User collection response", * @SWG\Schema(ref = "#/definitions/User") * ), * ) */ public function actionIndex() { $dataProvider = new ActiveDataProvider([ 'query' => User::find(), ]); return $dataProvider; } }
- Creating
User
definition
You need to create folder app/models/definitions
and add User
definition class as follows:
<?php namespace app\models\definitions; /** * @SWG\Definition(required={"username", "email"}) * * @SWG\Property(property="id", type="integer") * @SWG\Property(property="email", type="string") * @SWG\Property(property="username", type="string") */ class User { }
- Configuring URL Rules
Then, modify the configuration of the urlManager component in your application configuration:
'urlManager' => [ 'enablePrettyUrl' => true, 'enableStrictParsing' => true, 'showScriptName' => false, 'rules' => [ 'GET,HEAD users' => 'user/index', ], ]
- Enabling JSON Input
To let the API accept input data in JSON format, configure the parsers property of the request application component to use the yii\web\JsonParser
for JSON input:
'request' => [ 'parsers' => [ 'application/json' => 'yii\web\JsonParser', ] ]
Trying it Out
Now you can access to swagger documentation section through the following URL:
http://localhost/path/to/index.php?r=site/docs
View in the browser
Support us
Does your business depend on our contributions? Reach out and support us on Patreon. All pledges will be dedicated to allocating workforce on maintenance and new awesome stuff.