sadi01 / yii2-swagger
Swagger UI v3 intergation with yii2
1.0.1
2022-11-14 10:15 UTC
Requires
- bower-asset/swagger-ui: ~3.1
- yiisoft/yii2: ~2.0.14
- zircote/swagger-php: ^4.5
This package is auto-updated.
Last update: 2024-10-14 15:43:00 UTC
README
This module integrate swagger-php and swagger-ui v3.
Installation
The preferred way to install this extension is through composer.
Either run
php composer.phar require sadi01/yii2-swagger:dev-master
or add
"sadi01/yii2-swagger": "dev-master"
to the require section of your composer.json
file.
Usage
Once the extension is installed, simply use it in your code by :
You set url, where locate json file OR set path for scan
'modules' => [ ... 'swagger' => [ 'class' => \sadi01\swagger\Module::class, // 'url' => 'http://petstore.swagger.io/v2/swagger.json', 'path' => '@frontend/modules/api', // disable page with your logic 'isDisable' => function () { return false; }, // replace placeholders in swagger content 'afterRender' => function ($content) { $content = str_replace('{{host}}', 'http://example.com', $content); $content = str_replace('{{basePath}}', '/api/v1', $content); return $content; } ] ... ],
Now you open yourdomain.com/swagger and see API documentation
Example Module
/** * Class Module Api * * * @SWG\Swagger( * basePath="{{basePath}}", * host="{{host}}", * schemes={"http"}, * @SWG\Info( * version="1.0", * title="Example API", * @SWG\Contact(name="Example", url="http://example.ru"), * ), * @SWG\Definition( * definition="Error", * required={"code", "message"}, * @SWG\Property( * property="code", * type="integer", * format="int32" * ), * @SWG\Property( * property="message", * type="string" * ) * ) * ) */
Example controller
/** * @SWG\Post( * path = "/user-device/register", * tags = {"user-device"}, * operationId = "userDevice", * summary = "Регистрация устройства", * description = "Регистрация устройства", * produces = {"application/json"}, * consumes = {"application/json"}, * @SWG\Parameter( * in = "body", * name = "body", * description = "Тело запроса", * required = true, * type = "string", * @SWG\Schema(ref = "#/definitions/UserDeviceForm") * ), * @SWG\Response(response = 200, description = "success") *) * @throws HttpException */
Example form
/** * @SWG\Definition( * definition="UserDeviceForm", * required={"uuid", "token", "os", "json"}, * @SWG\Property( * property="uuid", * type="string", * description="UUID устройства", * example="e3243" * ), * @SWG\Property( * property="token", * type="string", * description="token для Google Fire Base", * example="e3243" * ), * @SWG\Property( * property="os", * type="string", * description="os устройства android|ios", * example="ios" * ), * @SWG\Property( * property="json", * type="string", * description="json достпные параметры устройства, название модели, версия ОС и др", * example="" * ) * ) */
TODO
- add cache
- add customization