├── .gitignore
├── README.md
├── composer.json
└── src
    ├── Assets.php
    ├── JsonAction.php
    ├── ViewAction.php
    └── view.php


/.gitignore:
--------------------------------------------------------------------------------
1 | /vendor
2 | /.idea
3 | composer.lock


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | Open Api Swagger 3 for Yii2 Framework
  2 | ================
  3 | 
  4 | Requirements
  5 | ------------
  6 |  - PHP 7.1
  7 |  - Yii2 Framework
  8 | 
  9 | Installation
 10 | ------------
 11 | 
 12 | The preferred way to install this wrapper is through [composer](http://getcomposer.org/download/).
 13 | 
 14 | ```bash
 15 | php composer.phar require genxoft/yii2-oas3 "*"
 16 | ```
 17 | 
 18 | or
 19 | 
 20 | ```bash
 21 | composer require genxoft/yii2-oas3 "*"
 22 | ```
 23 | 
 24 | or add to the require section of `composer.json`
 25 | 
 26 | ```
 27 | "genxoft/yii2-oas3" : "*"
 28 | ```
 29 | 
 30 | Integration
 31 | -----
 32 | 
 33 | Add action to web controller (for example SiteController.php):
 34 | 
 35 | ```php
 36 | public function actions()
 37 | {
 38 |     return [
 39 |         'api-docs' => [
 40 |             'class' => 'genxoft\swagger\ViewAction',
 41 |             'apiJsonUrl' => \yii\helpers\Url::to(['/site/api-json'], true),
 42 |         ],
 43 |         'api-json' => [
 44 |             'class' => 'genxoft\swagger\JsonAction',
 45 |             'dirs' => [
 46 |                 Yii::getAlias('@api/modules/api/controllers'),
 47 |                 Yii::getAlias('@api/modules/api/models'),
 48 |                 Yii::getAlias('@api/models'),
 49 |             ],
 50 |         ],
 51 |     ];
 52 | }
 53 | ```
 54 | 
 55 | Open Api Swagger 3 example annotation
 56 | -------------------------------------
 57 | 
 58 | Api server description
 59 | 
 60 | ```php
 61 | /**
 62 |  * @OA\Info(
 63 |  *   version="1.0",
 64 |  *   title="Application API",
 65 |  *   description="Server - Mobile app API",
 66 |  *   @OA\Contact(
 67 |  *     name="John Smith",
 68 |  *     email="john@example.com",
 69 |  *   ),
 70 |  * ),
 71 |  * @OA\Server(
 72 |  *   url="https://example.com/api",
 73 |  *   description="main server",
 74 |  * )
 75 |  * @OA\Server(
 76 |  *   url="https://dev.example.com/api",
 77 |  *   description="dev server",
 78 |  * )
 79 |  */
 80 |  
 81 | class DefaultController extends Controller
 82 | {
 83 | ...
 84 | ```
 85 | 
 86 | Controller annotation
 87 | 
 88 | ```php
 89 | /**
 90 |  * @OA\Get(path="/",
 91 |  *   summary="Handshake",
 92 |  *   tags={"handshake"},
 93 |  *   @OA\Parameter(
 94 |  *     name="access-token",
 95 |  *     in="header",
 96 |  *     required=false,
 97 |  *     @OA\Schema(
 98 |  *       type="string"
 99 |  *     )
100 |  *   ),
101 |  *   @OA\Response(
102 |  *     response=200,
103 |  *     description="Returns Hello object",
104 |  *     @OA\MediaType(
105 |  *         mediaType="application/json",
106 |  *         @OA\Schema(ref="#/components/schemas/Hello"),
107 |  *     ),
108 |  *   ),
109 |  * )
110 |  */
111 | public function actionIndex()
112 | {
113 | ... 
114 | ```
115 | 
116 | Model annotation
117 | 
118 | ```php
119 | /**
120 |  *@OA\Schema(
121 |  *  schema="Hello",
122 |  *  @OA\Property(
123 |  *     property="message",
124 |  *     type="string",
125 |  *     description="Text message"
126 |  *  ),
127 |  *  @OA\Property(
128 |  *     property="time",
129 |  *     type="integer",
130 |  *     description="Server current Unix time"
131 |  *  ),
132 |  *  @OA\Property(
133 |  *     property="date",
134 |  *     type="string",
135 |  *     format="date-time",
136 |  *     description="Server current date time"
137 |  *  )
138 |  *)
139 |  */
140 | class Hello extends Model
141 | {
142 | ...
143 | ```
144 | 
145 | ## Donate
146 | <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=2PURUX2SHUD9E"><img src="https://www.paypalobjects.com/en_US/RU/i/btn/btn_donateCC_LG.gif"></a>
147 | 
148 | ## LICENSE
149 | 
150 | This curl wrapper is released under the [MIT license](https://github.com/walkor/workerman/blob/master/MIT-LICENSE.txt).


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "genxoft/yii2-oas3",
 3 |     "description": "Yii2 Open Api Swagger 3 integration",
 4 |     "keywords": ["open-api","swagger","rest", "restfull", "json", "yii2"],
 5 |     "type": "library",
 6 |     "require": {
 7 |         "php": ">=7.1",
 8 |         "yiisoft/yii2": "~2.0",
 9 |         "ext-json": "*",
10 |         "zircote/swagger-php": "^3.0",
11 |         "bower-asset/swagger-ui": "^3.20"
12 |     },
13 |     "license": "MIT",
14 |     "authors": [
15 |         {
16 |             "name": "Simon Rodin",
17 |             "homepage": "http://rodin.red/",
18 |             "email": "master@genx.ru"
19 |         }
20 |     ],
21 |     "autoload": {
22 |         "psr-4": {
23 |             "genxoft\\swagger\\": "src/"
24 |         }
25 |     },
26 |     "minimum-stability": "stable"
27 | }
28 | 


--------------------------------------------------------------------------------
/src/Assets.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | /**
 3 |  * Yii2 php swagger module
 4 |  *
 5 |  * @author    Simon Rodin <master@genx.ru>
 6 |  * @license   http://opensource.org/licenses/MIT MIT Public
 7 |  * @link      https://github.com/genxoft/yii2-oas3
 8 |  *
 9 |  */
10 | 
11 | namespace genxoft\swagger;
12 | 
13 | use yii\web\AssetBundle;
14 | use yii\web\View;
15 | 
16 | class Assets extends AssetBundle
17 | {
18 |     public $sourcePath = '@bower/swagger-ui/dist';
19 |     
20 |     public $js = [
21 |         'swagger-ui-bundle.js',
22 |         'swagger-ui-standalone-preset.js',
23 |     ];
24 |     
25 |     public $jsOptions = [
26 |         'position' => View::POS_HEAD,
27 |     ];
28 |     
29 |     public $css = [
30 |         [
31 |             'swagger-ui.css',
32 |             'media' => 'screen, print',
33 |         ],
34 |     ];
35 | }
36 | 


--------------------------------------------------------------------------------
/src/JsonAction.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | /**
 3 |  * Yii2 php swagger module
 4 |  *
 5 |  * @author    Simon Rodin <master@genx.ru>
 6 |  * @license   http://opensource.org/licenses/MIT MIT Public
 7 |  * @link      https://github.com/genxoft/yii2-oas3
 8 |  *
 9 |  */
10 | 
11 | namespace genxoft\swagger;
12 | 
13 | use Yii;
14 | use yii\base\Action;
15 | use yii\web\Response;
16 | use Symfony\Component\Finder\Finder;
17 | 
18 | class JsonAction extends Action
19 | {
20 |     /**
21 |      * @var string|array|Finder directory(s) or filename(s) with open api annotations.
22 |      */
23 |     public $dirs;
24 | 
25 |     /**
26 |      * @var array
27 |      *   exclude: string|array $exclude The directory(s) or filename(s) to exclude (as absolute or relative paths)
28 |      *   analyser: defaults to StaticAnalyser
29 |      *   analysis: defaults to a new Analysis
30 |      *   processors: defaults to the registered processors in Analysis
31 |      */
32 |     public $scanOptions = [];
33 | 
34 |     /**
35 |      * @inheritdoc
36 |      */
37 |     public function run()
38 |     {
39 |         $this->initCors();
40 | 
41 |         Yii::$app->response->format = Response::FORMAT_JSON;
42 | 
43 |         return \OpenApi\scan($this->dirs, $this->scanOptions);
44 |     }
45 | 
46 |     /**
47 |      * Init cors.
48 |      */
49 |     protected function initCors()
50 |     {
51 |         $headers = Yii::$app->getResponse()->getHeaders();
52 | 
53 |         $headers->set('Access-Control-Allow-Headers', 'Content-Type');
54 |         $headers->set('Access-Control-Allow-Methods', 'GET, POST, DELETE, PUT');
55 |         $headers->set('Access-Control-Allow-Origin', '*');
56 |         $headers->set('Allow', 'OPTIONS,HEAD,GET');
57 |     }
58 | }
59 | 


--------------------------------------------------------------------------------
/src/ViewAction.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | /**
 3 |  * Yii2 php swagger module
 4 |  *
 5 |  * @author    Simon Rodin <master@genx.ru>
 6 |  * @license   http://opensource.org/licenses/MIT MIT Public
 7 |  * @link      https://github.com/genxoft/yii2-oas3
 8 |  *
 9 |  */
10 | 
11 | namespace genxoft\swagger;
12 | 
13 | use Yii;
14 | use yii\base\Action;
15 | use yii\web\Response;
16 | 
17 | class ViewAction extends Action
18 | {
19 |     /**
20 |      * @var string
21 |      * Open Api Swagger Json URL
22 |      */
23 |     public $apiJsonUrl;
24 | 
25 |     /**
26 |      * Action runner
27 |      * @return string
28 |      */
29 |     public function run()
30 |     {
31 |         Yii::$app->getResponse()->format = Response::FORMAT_HTML;
32 | 
33 |         return $this->controller->view->renderFile(__DIR__ . '/view.php', [
34 |             'apiJsonUrl' => $this->apiJsonUrl,
35 |         ], $this->controller);
36 |     }
37 | }
38 | 


--------------------------------------------------------------------------------
/src/view.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | /**
 3 |  * Yii2 php swagger module
 4 |  *
 5 |  * @author    Simon Rodin <master@genx.ru>
 6 |  * @license   http://opensource.org/licenses/MIT MIT Public
 7 |  * @link      https://github.com/genxoft/yii2-oas3
 8 |  *
 9 |  */
10 | 
11 | /** @var string $apiJsonUrl */
12 | 
13 | use genxoft\swagger\Assets;
14 | Assets::register($this);
15 | 
16 | ?>
17 | <?php $this->beginPage() ?>
18 | <!DOCTYPE html>
19 | <html lang="<?= Yii::$app->language ?>">
20 | <head>
21 |     <meta charset="UTF-8">
22 |     <title>Swagger UI</title>
23 |     <?php $this->head() ?>
24 | </head>
25 | 
26 | <body style="margin:0;">
27 | <?php $this->beginBody() ?>
28 | <div id="swagger-ui"></div>
29 | <script>
30 |     window.onload = function() {
31 |         // Begin Swagger UI call region
32 |         let ui = SwaggerUIBundle({
33 |             url: '<?= $apiJsonUrl; ?>',
34 |             dom_id: '#swagger-ui',
35 |             deepLinking: true,
36 |             presets: [
37 |                 SwaggerUIBundle.presets.apis,
38 |                 SwaggerUIStandalonePreset
39 |             ],
40 |             plugins: [
41 |                 SwaggerUIBundle.plugins.DownloadUrl
42 |             ],
43 |             layout: "StandaloneLayout"
44 |         });
45 |         window.ui = ui
46 |     }
47 | </script>
48 | 
49 | <?php $this->endBody() ?>
50 | </body>
51 | </html>
52 | <?php $this->endPage() ?>
53 | 


--------------------------------------------------------------------------------