ignatenkovnikita/yii2-swagger

Swagger UI v3 intergation with yii2

v1.5 2022-08-01 13:41 UTC

Requires

• bower-asset/swagger-ui: >3.1
• yiisoft/yii2: ^2.0.0
• zircote/swagger-php: >2.0

MIT

• Ignatenkov Nikita

• api
• restful
• extension
• document
• swagger
• yii2

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 ignatenkovnikita/yii2-swagger:dev-master

or add

"ignatenkovnikita/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' => \ignatenkovnikita\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

Donate