lichunqiang / yii2-swagger Goto Github PK

View Code? Open in Web Editor NEW

149.0 10.0 47.0 61 KB

yii2 with swagger-php

Home Page: https://packagist.org/packages/light/yii2-swagger

License: MIT License

PHP 100.00%

swagger-php yii2-swagger yii yii2 restful

yii2-swagger's Introduction

Yii2 Swagger Extension

swagger-php integration with yii2.

Integration swagger-ui with swagger-php.

Installation

The preferred way to install this extension is through composer.

Either run

php composer.phar require --prefer-dist light/yii2-swagger "~3.0" --dev

or add

"light/yii2-swagger": "~3.0"

to the require section of your composer.json file.

Usage

Configure two action as below:

public function actions()
{
    return [
        //The document preview addesss:http://api.yourhost.com/site/doc
        'doc' => [
            'class' => 'light\swagger\SwaggerAction',
            'restUrl' => \yii\helpers\Url::to(['/site/api'], true),
        ],
        //The resultUrl action.
        'api' => [
            'class' => 'light\swagger\SwaggerApiAction',
            //The scan directories, you should use real path there.
            'scanDir' => [
                Yii::getAlias('@api/modules/v1/swagger'),
                Yii::getAlias('@api/modules/v1/controllers'),
                Yii::getAlias('@api/modules/v1/models'),
                Yii::getAlias('@api/models'),
            ],
            //The security key
            'api_key' => 'balbalbal',
        ],
    ];
}

For security, you can config api key for protection.

Caching

public function actions()
{
    return [
        // ...
        'api' => [
            // ...
            'cache' => 'cache',
            'cacheKey' => 'api-swagger-cache', // default is 'api-swagger-cache'
        ],
    ];
}

Clear cache

Access clear cache url YOUR_API_URL?clear-cache or YOUR_API_URL?api_key=YOUR_API_KEY&clear-cache

Example: curl 'http://localhost/v1/swagger/api?clear-cache'

you will see: Succeed clear swagger api cache.

Finally

If there also some confused, you can refer the Demo.

License

yii2-swagger's People

Contributors

Stargazers

Watchers

Forkers

phpsong maxkos twobug idarex maxwelldu drzloy sysenshang lihaobin0320 dut3062796s delpfine zhangkg bradliu as5772830 ratanasoth ignatenkovnikita xloading andrey-ognermedia mcsneaky mishatrinex nocc dreaminf sensetivity fantomx1-github oleyur ilhomjonkurbanov songlipeng2003 alexyandy2016 digizijn lovecode1991 robote13 feixuelove mohammedabdi92 yiicode101 haohetao gitgrupoift joester89 jimersylee fhernandezn ricco381 baitu-open gabrielunb kualkua ik-veon-dev mikk150 krakozaber

yii2-swagger's Issues

Is it possible to update to Swagger UI v.3?

Hi!

Thanks a lot for this wonderful integration module.
Could you please advise whether it is possible to update it to support Swagger UI v.3.*?
There is a number of some useful updates after 2.2.10 which can be rather useful for everyone.

Thanks a lot in advance!

v1.0.3 Update not working

Hi,
After today update the extension stop working.

We have some js errors as:

"NetworkError: 404 Not Found - /assets/80322b46/lib/underscore-min.js"
"NetworkError: 404 Not Found - /assets/80322b46/lib/highlight.7.3.pack.js"
"NetworkError: 404 Not Found - /assets/80322b46/lib/handlebars-2.0.0.js"

ReferenceError: SwaggerUi is not defined

Thanks

bower目前已经不维护，不建议引用相关依赖，对于swagger-ui的依赖建议修改为npm

Update to swagger-php 3.x

Are you planing to update to swagger-php 3.x?

Add in header basic auth.

  function addAuthorization() {
    var username = encodeURIComponent($('#input_username').val());
    var password = encodeURIComponent($('#input_password').val());
    if (username && username.trim() != "" && password && password.trim() != "") {
      var basicAuth = new SwaggerClient.PasswordAuthorization('basic', username, password);
      window.swaggerUi.api.clientAuthorizations.add("basicAuth", basicAuth);
    }
  }
  $('#input_username').change(addAuthorization);
  $('#input_password').change(addAuthorization);

bower-asset/swagger-ui 这个包已经失踪了

bower-asset/swagger-ui 这个依赖包已经无效了，结果导致不能安装。

[QUESTION] How do I personalize Swagger

How can I personalize or change the Swagger theme?

Support "bower-asset/swagger-ui": "^4.1"?

Seems to work just fine, but just wondered if anything needed changing to work with 4.1 and above

composer 安装报错

1、composer require --prefer-dist light/yii2-swagger "~1.0.4" --dev

error
Your requirements could not be resolved to an installable set of packages.

Problem 1
- light/yii2-swagger 1.0.5 requires bower-asset/swagger-ui 2.2.10 -> no matching package found.
- light/yii2-swagger 1.0.4 requires bower-asset/swagger-ui 2.2.10 -> no matching package found.
- Installation request for light/yii2-swagger ~1.0.4 -> satisfiable by light/yii2-swagger[1.0.4, 1.0.5].

Potential causes:

A typo in the package name
The package is not available in a stable-enough version according to your minimum-stability setting
see https://getcomposer.org/doc/04-schema.md#minimum-stability for more details.

Read https://getcomposer.org/doc/articles/troubleshooting.md for further common problems.

2、composer require --prefer-dist light/yii2-swagger "~1.0.5" --dev

Your requirements could not be resolved to an installable set of packages.

Problem 1
- Installation request for light/yii2-swagger ~1.0.5 -> satisfiable by light/yii2-swagger[1.0.5].
- light/yii2-swagger 1.0.5 requires bower-asset/swagger-ui 2.2.10 -> no matching package found.

Potential causes:

A typo in the package name
The package is not available in a stable-enough version according to your minimum-stability setting
see https://getcomposer.org/doc/04-schema.md#minimum-stability for more details.

Read https://getcomposer.org/doc/articles/troubleshooting.md for further common problems.

Installation failed, reverting ./composer.json to its original content.

PHP 7.4 support

Hello, @lichunqiang

With updating my project to php 7.4, got an exception

500 : {"name":"PHP User Warning","message":"Trying to access array offset on value of type null","code":512,"type":"yii\base\ErrorException","file":"/app/vendor/zircote/swagger-php/src/Logger.php","line":38,

It happens cause of old version of zircote/swagger-php usage and it is fixed it newer versions.

Is there any chances to update zircote/swagger-php library to v3.0.3, which has php 7.4 support (https://github.com/zircote/swagger-php/releases/tag/3.0.3)?

The package is not available in a stable-enough version according to your minimum-stability setting

I am getting below error even I have updated my composer

The package is not available in a stable-enough version according to your minimum-stability setting

composer

"minimum-stability": "dev"

Ignoring annotation issue

Class RestController
@package api\controllers
@SWG\Swagger(
     basePath="/api",
     produces={"application/json"},
     consumes={"application/x-www-form-urlencoded"},
     schemes={"http"},
     @SWG\Info(
         version="1.0.0",
         title="Api",
         @SWG\Contact(name="Author", email="[email protected]"),
     ),
    @SWG\SecurityScheme(
         securityDefinition="Bearer",
         type="apiKey",
         in="header",
         name="Authorization",
         description="Auth Bearer Token format as 'Bearer <access_token>'
    )
 )

For some reason the this section is completely ignored by parser.
This generated result for the api is:
{"swagger":"2.0","paths":{"/api/login":{"post":{"tags":["User"]...
Which is clearly missing the basePath, info and security definitions.

Create branch for 3.x

Can you please make branch for 3.x so I can make PR to there?

Error 500 Zircote in swagger in new version 3.0.3

yii\base\ErrorException: Skipping unknown \__Application in /app/vendor/zircote/swagger-php/src/Loggers/DefaultLogger.php:31
Stack trace:
#0 [internal function]: yii\base\ErrorHandler->handleError(512, 'Skipping unknow...', '/app/vendor/zir...', 31, Array)
#1 /app/vendor/zircote/swagger-php/src/Loggers/DefaultLogger.php(31): trigger_error('Skipping unknow...', 512)
#2 /app/vendor/psr/log/Psr/Log/AbstractLogger.php(85): OpenApi\Loggers\DefaultLogger->log('warning', 'Skipping unknow...', Array)
#3 /app/vendor/zircote/swagger-php/src/Analysers/ReflectionAnalyser.php(80): Psr\Log\AbstractLogger->warning('Skipping unknow...')
#4 /app/vendor/zircote/swagger-php/src/Analysers/ReflectionAnalyser.php(54): OpenApi\Analysers\ReflectionAnalyser->analyzeFqdn('\\__Application', Object(OpenApi\Analysis), Array)
#5 /app/vendor/zircote/swagger-php/src/Generator.php(433): OpenApi\Analysers\ReflectionAnalyser->fromFile('/app/config/__a...', Object(OpenApi\Context))
#6 /app/vendor/zircote/swagger-php/src/Generator.php(396): OpenApi\Generator->scanSources(Object(Symfony\Component\Finder\Finder), Object(OpenApi\Analysis), Object(OpenApi\Context))
#7 /app/vendor/zircote/swagger-php/src/Generator.php(348): OpenApi\Generator->generate(Object(Symfony\Component\Finder\Finder), Object(OpenApi\Analysis), true)
#8 /app/vendor/light/yii2-swagger/src/SwaggerApiAction.php(156): OpenApi\Generator::scan(Object(Symfony\Component\Finder\Finder), Array)
#9 /app/vendor/light/yii2-swagger/src/SwaggerApiAction.php(110): light\swagger\SwaggerApiAction->getSwagger()
#10 [internal function]: light\swagger\SwaggerApiAction->run()
#11 /app/vendor/yiisoft/yii2/base/Action.php(93): call_user_func_array(Array, Array)
#12 /app/vendor/yiisoft/yii2/base/Controller.php(178): yii\base\Action->runWithParams(Array)
#13 /app/vendor/yiisoft/yii2/base/Module.php(552): yii\base\Controller->runAction('api', Array)
#14 /app/vendor/yiisoft/yii2/web/Application.php(103): yii\base\Module->runAction('default/api', Array)
#15 /app/vendor/yiisoft/yii2/base/Application.php(384): yii\web\Application->handleRequest(Object(yii\web\Request))
#16 /app/api/index.php(16): yii\base\Application->run()
#17 {main}

Fail to open swagger app:
PHP version: 7.4.30
Yii version 2.0.45
light/yii2-swagger v3.0.3

swithc to Generator class

https://zircote.github.io/swagger-php/Generator-migration.html#motivation

Install config

Please specify the installation guide.
About create controller, Models, bla bla... from the beginning and more specific!
I am a newbie for this field so I do not know how to config to use it!
Sth like:
`/**

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"
```
```
    )
```
```
)
```
)
*/`

Broken with zircote/swagger-php v2.0.11

Since the update of zircote/swagger-php to 2.0.11, this package is broken.
The definitions can´t be found.

Error in bundle

The below exception apperse after entering the site/doc:

The file or directory to be published does not exist: /myDomin.com/frontend/vendor/bower/swagger-ui/dist

Can anyone help me with this?

add the json file generate helper

So we can ensure the api is stable and can publish the main version.

api_key 在nginx下通过header发送，无法验证。

新版本的swagger ui 不在使用get验证登录，改用header。apache下正常。
nginx下自定义header，
在nginx.conf 开启
underscores_in_headers on; #默认off
api_key会解析为api-key，php无法获取进行验证，报错如下，建议统一api-key

{"securityDefinitions":{"api_key":{"in":"header","type":"apiKey","name":"api_key"}},"swagger":"2.0","schemes":["http"],"info":{"title":"Please take authentication firstly."}}

参考：http://stackoverflow.com/questions/22856136/why-underscores-are-forbidden-in-http-header-names