├── .php_cs
├── SwaggerAsset.php
├── composer.json
├── LICENSE
├── SwaggerUIRenderer.php
├── OpenAPIRenderer.php
├── views
└── index.php
└── README.md
/.php_cs:
--------------------------------------------------------------------------------
1 | exclude('vendor')
5 | ->in([__DIR__]);
6 |
7 | $config = PhpCsFixer\Config::create()
8 | ->setUsingCache(false)
9 | ->setRules([
10 | '@Symfony' => true,
11 | 'phpdoc_align' => false,
12 | 'phpdoc_summary' => false,
13 | 'phpdoc_inline_tag' => false,
14 | 'pre_increment' => false,
15 | 'heredoc_to_nowdoc' => false,
16 | 'cast_spaces' => false,
17 | 'include' => false,
18 | 'phpdoc_no_package' => false,
19 | 'concat_space' => ['spacing' => 'one'],
20 | 'ordered_imports' => true,
21 | 'array_syntax' => ['syntax' => 'short'],
22 | 'yoda_style' => false,
23 | ])
24 | ->setFinder($finder);
25 |
26 | return $config;
27 |
--------------------------------------------------------------------------------
/SwaggerAsset.php:
--------------------------------------------------------------------------------
1 | =7.1.0",
19 | "yiisoft/yii2": "~2.0.12",
20 | "zircote/swagger-php": "^2.0",
21 | "bower-asset/swagger-ui": "^3.1"
22 | },
23 | "require-dev": {
24 | "friendsofphp/php-cs-fixer": "~2.0",
25 | "phpunit/phpunit": "~6.0"
26 | },
27 | "autoload": {
28 | "psr-4": {
29 | "yii2mod\\swagger\\": ""
30 | }
31 | },
32 | "repositories": [
33 | {
34 | "type": "composer",
35 | "url": "https://asset-packagist.org"
36 | }
37 | ]
38 | }
39 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2017 Yii2 modules & extensions
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/SwaggerUIRenderer.php:
--------------------------------------------------------------------------------
1 | controller->layout = $this->layout;
38 |
39 | return $this->controller->render($this->view, [
40 | 'restUrl' => $this->restUrl,
41 | ]);
42 | }
43 | }
44 |
--------------------------------------------------------------------------------
/OpenAPIRenderer.php:
--------------------------------------------------------------------------------
1 | cache !== null) {
59 | $this->cache = Instance::ensure($this->cache, Cache::class);
60 | }
61 | }
62 |
63 | /**
64 | * @inheritdoc
65 | */
66 | public function run(): Response
67 | {
68 | $this->enableCORS();
69 |
70 | return $this->controller->asJson($this->getSwaggerDocumentation());
71 | }
72 |
73 | /**
74 | * Scan the filesystem for swagger annotations and build swagger-documentation.
75 | *
76 | * @return Swagger
77 | */
78 | protected function getSwaggerDocumentation(): Swagger
79 | {
80 | if (!$this->cache instanceof Cache) {
81 | return \Swagger\scan($this->scanDir, $this->scanOptions);
82 | }
83 |
84 | return $this->cache->getOrSet($this->cacheKey, function () {
85 | return \Swagger\scan($this->scanDir, $this->scanOptions);
86 | }, $this->cacheDuration);
87 | }
88 |
89 | /**
90 | * Enable CORS
91 | */
92 | protected function enableCORS(): void
93 | {
94 | $headers = Yii::$app->getResponse()->getHeaders();
95 |
96 | $headers->set('Access-Control-Allow-Headers', 'Content-Type, api_key, Authorization');
97 | $headers->set('Access-Control-Allow-Methods', 'GET, POST, DELETE, PUT');
98 | $headers->set('Access-Control-Allow-Origin', '*');
99 | }
100 | }
101 |
--------------------------------------------------------------------------------
/views/index.php:
--------------------------------------------------------------------------------
1 |
10 | beginPage(); ?>
11 |
12 |
13 |
14 |
15 | Swagger UI
16 | head(); ?>
17 |
19 |
37 |
38 |
39 |
40 | beginBody(); ?>
41 |
75 |
76 |
77 |
100 | endBody(); ?>
101 |
102 |
103 | endPage(); ?>
104 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
2 |
3 | 
4 |
5 |
Swagger Documentation Generator for Yii2 Framework
6 |
7 |
8 |
9 | Swagger/OpenAPI Documentation Generator for Yii2 Framework.
10 |
11 | [](https://packagist.org/packages/yii2mod/yii2-swagger)
12 | [](https://packagist.org/packages/yii2mod/yii2-swagger)
13 | [](https://packagist.org/packages/yii2mod/yii2-swagger)
14 | [](https://travis-ci.org/yii2mod/yii2-swagger)
15 |
16 | Installation
17 | ------------
18 |
19 | The preferred way to install this extension is through [composer](http://getcomposer.org/download/).
20 |
21 | Either run
22 |
23 | ```
24 | php composer.phar require --prefer-dist yii2mod/yii2-swagger "*"
25 | ```
26 |
27 | or add
28 |
29 | ```
30 | "yii2mod/yii2-swagger": "*"
31 | ```
32 |
33 | to the require section of your composer.json.
34 |
35 | Configuration
36 | -------------
37 | You need to configure two actions as follows:
38 |
39 | ```php
40 | [
65 | 'class' => 'yii2mod\swagger\SwaggerUIRenderer',
66 | 'restUrl' => Url::to(['site/json-schema']),
67 | ],
68 | 'json-schema' => [
69 | 'class' => 'yii2mod\swagger\OpenAPIRenderer',
70 | // Тhe list of directories that contains the swagger annotations.
71 | 'scanDir' => [
72 | Yii::getAlias('@app/controllers'),
73 | Yii::getAlias('@app/models'),
74 | ],
75 | ],
76 | 'error' => [
77 | 'class' => 'yii\web\ErrorAction',
78 | ],
79 | ];
80 | }
81 | }
82 | ```
83 |
84 | Usage
85 | -------------
86 | 1) Creating a Controller
87 |
88 | First, create a controller class `app\controllers\UserController` as follows:
89 |
90 | ```php
91 | namespace app\controllers;
92 |
93 | use app\models\User;
94 | use yii\data\ActiveDataProvider;
95 | use yii\rest\Controller;
96 |
97 | /**
98 | * Class UserController
99 | */
100 | class UserController extends Controller
101 | {
102 | /**
103 | * @SWG\Get(path="/user",
104 | * tags={"User"},
105 | * summary="Retrieves the collection of User resources.",
106 | * @SWG\Response(
107 | * response = 200,
108 | * description = "User collection response",
109 | * @SWG\Schema(ref = "#/definitions/User")
110 | * ),
111 | * )
112 | */
113 | public function actionIndex()
114 | {
115 | $dataProvider = new ActiveDataProvider([
116 | 'query' => User::find(),
117 | ]);
118 |
119 | return $dataProvider;
120 | }
121 | }
122 | ```
123 |
124 | 2) Creating `User` definition
125 |
126 | You need to create folder `app/models/definitions` and add `User` definition class as follows:
127 |
128 | ```php
129 | [
150 | 'enablePrettyUrl' => true,
151 | 'enableStrictParsing' => true,
152 | 'showScriptName' => false,
153 | 'rules' => [
154 | 'GET,HEAD users' => 'user/index',
155 | ],
156 | ]
157 | ```
158 |
159 | 4) Enabling JSON Input
160 |
161 | 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:
162 | ```php
163 | 'request' => [
164 | 'parsers' => [
165 | 'application/json' => 'yii\web\JsonParser',
166 | ]
167 | ]
168 | ```
169 |
170 | Trying it Out
171 | -------------
172 |
173 | Now you can access to swagger documentation section through the following URL:
174 |
175 | http://localhost/path/to/index.php?r=site/docs
176 |
177 | **View in the browser**
178 |
179 | 
180 |
181 |
182 | ## Support us
183 |
184 | Does your business depend on our contributions? Reach out and support us on [Patreon](https://www.patreon.com/yii2mod).
185 | All pledges will be dedicated to allocating workforce on maintenance and new awesome stuff.
186 |
--------------------------------------------------------------------------------