@@ -28,7 +28,11 @@ passing PHPUnit tests.
28
28
29
29
## Installation
30
30
31
- 1 . Install the package using the following command: ` composer require ronasit/laravel-swagger `
31
+ 1 . Install the package using the following command:
32
+
33
+ ``` sh
34
+ composer require ronasit/laravel-swagger
35
+ ```
32
36
33
37
> *** Note***
34
38
>
@@ -43,45 +47,39 @@ passing PHPUnit tests.
43
47
> ],
44
48
> ```
45
49
46
- 2 . Run `php artisan vendor:publish --provider=RonasIT\\AutoDoc\\AutoDocServiceProvider`
50
+ 1 . Run `php artisan vendor:publish --provider=RonasIT\\AutoDoc\\AutoDocServiceProvider`
47
51
1. Add `\RonasIT\AutoDoc\Http\Middleware\AutoDocMiddleware::class` middleware to the global HTTP middleware list `bootstrap\app.php`:
48
52
49
53
```php
50
54
return Application::configure(basePath: dirname(__DIR__))
51
55
->withMiddleware(function (Middleware $middleware) {
52
56
$middleware->use([
53
- ...
57
+ // ...
54
58
\RonasIT\AutoDoc\Http\Middleware\AutoDocMiddleware::class,
55
59
]);
56
60
});
57
61
```
58
62
59
- 4 . Add ` \RonasIT\AutoDoc\Traits\AutoDocTestCaseTrait ` trait to ` tests/TestCase.php `
63
+ 4 . Add ` \RonasIT\AutoDoc\Traits\AutoDocTestCaseTrait ` trait to your ` tests/TestCase.php ` class
60
64
1 . Configure documentation saving using one of the next ways:
61
65
- Add ` SwaggerExtension ` to the ` <extensions> ` block of your ` phpunit.xml ` .
62
- ** Please note that this way will be removed after updating**
63
- ** PHPUnit up to 10 version (https://github.com/sebastianbergmann/phpunit/issues/4676 )**
64
66
65
67
``` xml
66
68
<phpunit >
69
+ //...
67
70
<extensions >
68
71
<bootstrap class =" RonasIT\AutoDoc\Support\PHPUnit\Extensions\SwaggerExtension" />
69
72
</extensions >
70
- <testsuites >
71
- <testsuite name =" Feature" >
72
- <directory suffix =" Test.php" >./tests/Feature</directory >
73
- </testsuite >
74
- </testsuites >
75
73
</phpunit >
76
74
```
77
75
- Call ` php artisan swagger:push-documentation ` console command after
78
- the ` tests ` stage in your CI/CD configuration
76
+ the ` tests ` stage.
79
77
80
78
## Usage
81
79
82
80
### Basic usage
83
81
84
- 1 . Create request class:
82
+ 1 . Create a request class:
85
83
86
84
``` php
87
85
<?php
@@ -130,6 +128,7 @@ passing PHPUnit tests.
130
128
}
131
129
132
130
```
131
+
133
132
> ***Note***
134
133
>
135
134
> For correct working of plugin you'll have to dispose all the validation rules
@@ -138,7 +137,7 @@ passing PHPUnit tests.
138
137
> Plugin will take validation rules from the request class and generate fields description
139
138
> of input parameter.
140
139
141
- 2. Create a controller and a method for your route :
140
+ 1. Implement request handling in the corresponding controller class :
142
141
143
142
```php
144
143
<?php
@@ -160,10 +159,10 @@ passing PHPUnit tests.
160
159
161
160
> ***Note***
162
161
>
163
- > Dependency injection of request class is optional but if it not presents,
164
- > the " Parameters" block in the API documentation will be empty.
162
+ > Dependency injection of the request class is optional, but if it isn't present,
163
+ > the ' Parameters' block in the API documentation will be empty.
165
164
166
- 3. Create test for API endpoint:
165
+ 3. Create a test for the API endpoint:
167
166
168
167
```php
169
168
public function testUpdate()
@@ -178,15 +177,15 @@ passing PHPUnit tests.
178
177
}
179
178
```
180
179
181
- 4. Run tests
182
- 5. Go to route defined in the `auto-doc.route` config
180
+ 4. Run the tests
181
+ 5. Go to the route which is defined in the `auto-doc.route` config
183
182
6. Profit!
184
183
185
184

186
185
187
186
### Annotations
188
187
189
- You can use the following annotations in your request classes to customize documentation of your API endpoints :
188
+ You can use the following annotations in the corresponding request class to customize documentation of the API endpoint :
190
189
191
190
- **@summary** - short description of request
192
191
- **@description** - implementation notes
@@ -198,11 +197,6 @@ You can use the following annotations in your request classes to customize docum
198
197
>
199
198
> If you do not use request class, the summary and description and parameters will be empty.
200
199
201
- ### Configs
202
-
203
- - `auto-doc.route` - route for generated documentation
204
- - `auto-doc.basePath` - root of your API
205
-
206
200
### Custom driver
207
201
208
202
You can specify the way to collect and view documentation by creating your own custom driver.
@@ -212,8 +206,8 @@ You can find example of drivers [here](https://github.com/RonasIT/laravel-swagge
212
206
### Viewing OpenAPI documentation
213
207
214
208
As of version 2.2, the package includes the ability to switch between OpenAPI documentation
215
- viewers. To access different viewers, modify the `documentation_viewer` configuration.
216
- This change is reflected immediately, without the need to rebuild the documentation file.
209
+ viewers. To access different viewers, modify the `documentation_viewer` configuration or set the viewer using
210
+ the `SWAGGER_SPEC_VIEWER` env. This change is reflected immediately, without the need to rebuild the documentation file.
217
211
218
212
### Merging additional documentations
219
213
0 commit comments