Skip to content

Commit 6a8f91b

Browse files
astorozhevskyastorozhevsky
authored
Merge pull request #138 from RonasIT/dpankratov/update-readme
doc: update readme, add migration guide
2 parents 719a451 + 8a2779f commit 6a8f91b

File tree

10 files changed

+117
-77
lines changed

10 files changed

+117
-77
lines changed

‎MIGRATION-GUIDES.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# 3.0.1-beta
2+
3+
As package starting to work with new Open API specification, need to regenerate documentation file.
4+
5+
The base namespace of the package had also been changed, so you need to use new namespace in:
6+
7+
- `bootstrap\app.php` (`Http/Kernel.php` for Laravel <= 10), change namespace of
8+
`\RonasIT\Support\AutoDoc\Http\Middleware\AutoDocMiddleware` to
9+
`\RonasIT\AutoDoc\Http\Middleware\AutoDocMiddleware`;
10+
- `tests/TestCase.php`, change namespace of `\RonasIT\Support\AutoDoc\Tests\AutoDocTestCaseTrait` to
11+
`\RonasIT\AutoDoc\Traits\AutoDocTestCaseTrait`;
12+
- `phpunit.xml`, change namespace of extension from `RonasIT\Support\AutoDoc\Tests\PhpUnitExtensions\SwaggerExtension` to
13+
`RonasIT\AutoDoc\Support\PHPUnit\Extensions\SwaggerExtension`;
14+
- your custom documentation drivers, change interface from `RonasIT\AutoDoc\Interfaces\SwaggerDriverInterface` to
15+
`RonasIT\AutoDoc\Contracts\SwaggerDriverContract`.

‎config/auto-doc.php‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -51,8 +51,8 @@
5151
],
5252
'license' => [
5353
'name' => '',
54-
'url' => ''
55-
]
54+
'url' => '',
55+
],
5656
],
5757

5858
/*
@@ -80,13 +80,13 @@
8080
'jwt' => [
8181
'type' => 'apiKey',
8282
'name' => 'Authorization',
83-
'in' => 'header'
83+
'in' => 'header',
8484
],
8585
'laravel' => [
8686
'type' => 'apiKey',
8787
'name' => '__ym_uid',
88-
'in' => 'cookie'
89-
]
88+
'in' => 'cookie',
89+
],
9090
],
9191

9292
'defaults' => [
@@ -99,8 +99,8 @@
9999
'code-descriptions' => [
100100
'200' => 'Operation successfully done',
101101
'204' => 'Operation successfully done',
102-
'404' => 'This entity not found'
103-
]
102+
'404' => 'This entity not found',
103+
],
104104
],
105105

106106
/*
@@ -110,7 +110,7 @@
110110
|
111111
| The name of driver, which will collect and save documentation
112112
| Feel free to use your own driver class which should be inherited from
113-
| `RonasIT\AutoDoc\Interfaces\SwaggerDriverInterface` interface,
113+
| `RonasIT\AutoDoc\Contracts\SwaggerDriverContract` interface,
114114
| or one of our drivers from the `drivers` config:
115115
*/
116116
'driver' => env('SWAGGER_DRIVER', 'local'),
@@ -147,7 +147,7 @@
147147
*/
148148
'disk' => env('SWAGGER_STORAGE_DRIVER_DISK', 'public'),
149149
'production_path' => 'documentation.json',
150-
]
150+
],
151151
],
152152

153153
/*
@@ -184,5 +184,5 @@
184184
'development',
185185
],
186186

187-
'config_version' => '2.7',
187+
'config_version' => '2.8',
188188
];

‎phpunit.xml‎

Lines changed: 29 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,31 @@
11
<?xml version="1.0" encoding="UTF-8"?>
2-
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" backupGlobals="false" bootstrap="bootstrap/autoload.php" colors="true" processIsolation="false" stopOnFailure="false" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.4/phpunit.xsd" cacheDirectory=".phpunit.cache" backupStaticProperties="false">
3-
<coverage/>
4-
<testsuites>
5-
<testsuite name="Application Test Suite">
6-
<directory suffix="Test.php">./tests</directory>
7-
</testsuite>
8-
</testsuites>
9-
<php>
10-
<env name="APP_ENV" value="testing"/>
11-
<env name="CACHE_DRIVER" value="array"/>
12-
<env name="SESSION_DRIVER" value="array"/>
13-
<env name="QUEUE_DRIVER" value="sync"/>
14-
</php>
15-
<source>
16-
<include>
17-
<directory suffix=".php">./src</directory>
18-
</include>
19-
<exclude>
20-
<file>./app/Http/routes.php</file>
21-
<directory suffix=".php">./src/Tests</directory>
22-
</exclude>
23-
</source>
2+
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3+
backupGlobals="false"
4+
bootstrap="bootstrap/autoload.php"
5+
colors="true"
6+
processIsolation="false"
7+
stopOnFailure="false"
8+
xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.4/phpunit.xsd"
9+
cacheDirectory=".phpunit.cache"
10+
backupStaticProperties="false">
11+
<coverage/>
12+
<testsuites>
13+
<testsuite name="Application Test Suite">
14+
<directory suffix="Test.php">./tests</directory>
15+
</testsuite>
16+
</testsuites>
17+
<php>
18+
<env name="APP_ENV" value="testing"/>
19+
<env name="CACHE_DRIVER" value="array"/>
20+
<env name="SESSION_DRIVER" value="array"/>
21+
<env name="QUEUE_DRIVER" value="sync"/>
22+
</php>
23+
<source>
24+
<include>
25+
<directory suffix=".php">./src</directory>
26+
</include>
27+
<exclude>
28+
<file>./app/Http/routes.php</file>
29+
</exclude>
30+
</source>
2431
</phpunit>

‎readme.md‎

Lines changed: 51 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -30,37 +30,51 @@ passing PHPUnit tests.
3030

3131
1. Install the package using the following command: `composer require ronasit/laravel-swagger`
3232

33-
> ***Note***
34-
>
35-
> For Laravel 5.5 or later the package will be auto-discovered.
36-
> For older versions add the `AutoDocServiceProvider` to the
37-
> providers array in `config/app.php` as follow:
38-
>
39-
> ```php
40-
> 'providers' => [
41-
> // ...
42-
> RonasIT\AutoDoc\AutoDocServiceProvider::class,
43-
> ],
44-
> ```
45-
46-
1. Run `php artisan vendor:publish`
47-
2. Add `\RonasIT\AutoDoc\Http\Middleware\AutoDocMiddleware::class` middleware to the global HTTP middleware stack in `Http/Kernel.php`.
48-
3. Add `\RonasIT\AutoDoc\Tests\AutoDocTestCaseTrait` trait to `tests/TestCase.php`
49-
4. Configure documentation saving using one of the next ways:
50-
- Add `SwaggerExtension` to the `<extensions>` block of your `phpunit.xml`.
51-
**Please note that this way will be removed after updating**
52-
**PHPUnit up to 10 version (https://github.com/sebastianbergmann/phpunit/issues/4676)**
53-
```xml
54-
<extensions>
55-
<extension class="RonasIT\AutoDoc\Tests\PhpUnitExtensions\SwaggerExtension"/>
56-
</extensions>
57-
<testsuites>
58-
<testsuite name="Feature">
59-
<directory suffix="Test.php">./tests/Feature</directory>
60-
</testsuite>
61-
</testsuites>
62-
```
63-
- Call `php artisan swagger:push-documentation` console command after
33+
> ***Note***
34+
>
35+
> For Laravel 5.5 or later the package will be auto-discovered.
36+
> For older versions add the `AutoDocServiceProvider` to the
37+
> providers array in `config/app.php` as follow:
38+
>
39+
> ```php
40+
> 'providers' => [
41+
> ...
42+
> RonasIT\AutoDoc\AutoDocServiceProvider::class,
43+
> ],
44+
> ```
45+
46+
2. Run `php artisan vendor:publish --provider=RonasIT\\AutoDoc\\AutoDocServiceProvider`
47+
1. Add `\RonasIT\AutoDoc\Http\Middleware\AutoDocMiddleware::class` middleware to the global HTTP middleware list `bootstrap\app.php`:
48+
49+
```php
50+
return Application::configure(basePath: dirname(__DIR__))
51+
->withMiddleware(function (Middleware $middleware) {
52+
$middleware->use([
53+
...
54+
\RonasIT\AutoDoc\Http\Middleware\AutoDocMiddleware::class,
55+
]);
56+
});
57+
```
58+
59+
4. Add `\RonasIT\AutoDoc\Traits\AutoDocTestCaseTrait` trait to `tests/TestCase.php`
60+
1. Configure documentation saving using one of the next ways:
61+
- 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+
65+
```xml
66+
<phpunit>
67+
<extensions>
68+
<bootstrap class="RonasIT\AutoDoc\Support\PHPUnit\Extensions\SwaggerExtension"/>
69+
</extensions>
70+
<testsuites>
71+
<testsuite name="Feature">
72+
<directory suffix="Test.php">./tests/Feature</directory>
73+
</testsuite>
74+
</testsuites>
75+
</phpunit>
76+
```
77+
- Call `php artisan swagger:push-documentation` console command after
6478
the `tests` stage in your CI/CD configuration
6579

6680
## Usage
@@ -120,7 +134,7 @@ passing PHPUnit tests.
120134
>
121135
> For correct working of plugin you'll have to dispose all the validation rules
122136
> in the `rules()` method of your request class. Also, your request class
123-
> must be connected to the controller via [dependency injection](https://laravel.com/docs/9.x/container#introduction).
137+
> must be connected to the controller via [dependency injection](https://laravel.com/docs/11.x/container#introduction).
124138
> Plugin will take validation rules from the request class and generate fields description
125139
> of input parameter.
126140

@@ -191,7 +205,7 @@ You can use the following annotations in your request classes to customize docum
191205

192206
### Custom driver
193207

194-
You can specify the way to collect documentation by creating your own custom driver.
208+
You can specify the way to collect and view documentation by creating your own custom driver.
195209

196210
You can find example of drivers [here](https://github.com/RonasIT/laravel-swagger/tree/master/src/Drivers).
197211

@@ -206,6 +220,10 @@ This change is reflected immediately, without the need to rebuild the documentat
206220
The package supports the integration of the primary documentation with additional valid
207221
OpenAPI files specified in the `additional_paths` configuration.
208222

223+
## Migration guides
224+
225+
[3.0.1-beta](MIGRATION-GUIDES.md#301-beta)
226+
209227
## Contributing
210228

211229
Thank you for considering contributing to Laravel Swagger plugin! The contribution guide

‎src/Interfaces/SwaggerDriverInterface.php‎ renamed to ‎src/Contracts/SwaggerDriverContract.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
<?php
22

3-
namespace RonasIT\AutoDoc\Interfaces;
3+
namespace RonasIT\AutoDoc\Contracts;
44

5-
interface SwaggerDriverInterface
5+
interface SwaggerDriverContract
66
{
77
/**
88
* Save temporary data

‎src/Drivers/BaseDriver.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22

33
namespace RonasIT\AutoDoc\Drivers;
44

5-
use RonasIT\AutoDoc\Interfaces\SwaggerDriverInterface;
5+
use RonasIT\AutoDoc\Contracts\SwaggerDriverContract;
66

7-
abstract class BaseDriver implements SwaggerDriverInterface
7+
abstract class BaseDriver implements SwaggerDriverContract
88
{
99
protected string $tempFilePath;
1010

‎src/Services/SwaggerService.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,13 @@
1717
use RonasIT\AutoDoc\Exceptions\SwaggerDriverClassNotFoundException;
1818
use RonasIT\AutoDoc\Exceptions\UnsupportedDocumentationViewerException;
1919
use RonasIT\AutoDoc\Exceptions\WrongSecurityConfigException;
20-
use RonasIT\AutoDoc\Interfaces\SwaggerDriverInterface;
20+
use RonasIT\AutoDoc\Contracts\SwaggerDriverContract;
2121
use RonasIT\AutoDoc\Traits\GetDependenciesTrait;
2222
use RonasIT\AutoDoc\Validators\SwaggerSpecValidator;
2323
use Symfony\Component\HttpFoundation\Response;
2424

2525
/**
26-
* @property SwaggerDriverInterface $driver
26+
* @property SwaggerDriverContract $driver
2727
*/
2828
class SwaggerService
2929
{
@@ -124,7 +124,7 @@ protected function setDriver()
124124
$this->driver = app($className);
125125
}
126126

127-
if (!$this->driver instanceof SwaggerDriverInterface) {
127+
if (!$this->driver instanceof SwaggerDriverContract) {
128128
throw new InvalidDriverClassException($driver);
129129
}
130130
}

‎src/Tests/PhpUnitEventSubscribers/SwaggerSaveDocumentationSubscriber.php‎ renamed to ‎src/Support/PHPUnit/EventSubscribers/SwaggerSaveDocumentationSubscriber.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?php
22

3-
namespace RonasIT\AutoDoc\Tests\PhpUnitEventSubscribers;
3+
namespace RonasIT\AutoDoc\Support\PHPUnit\EventSubscribers;
44

55
use Illuminate\Contracts\Console\Kernel;
66
use PHPUnit\Event\Application\Finished;
@@ -23,4 +23,4 @@ protected function createApplication(): void
2323
$app->loadEnvironmentFrom('.env.testing');
2424
$app->make(Kernel::class)->bootstrap();
2525
}
26-
}
26+
}

‎src/Tests/PhpUnitExtensions/SwaggerExtension.php‎ renamed to ‎src/Support/PHPUnit/Extensions/SwaggerExtension.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
<?php
22

3-
namespace RonasIT\AutoDoc\Tests\PhpUnitExtensions;
3+
namespace RonasIT\AutoDoc\Support\PHPUnit\Extensions;
44

55
use PHPUnit\Runner\Extension\Extension as PhpunitExtension;
66
use PHPUnit\Runner\Extension\Facade as EventFacade;
77
use PHPUnit\Runner\Extension\ParameterCollection;
88
use PHPUnit\TextUI\Configuration\Configuration;
9-
use RonasIT\AutoDoc\Tests\PhpUnitEventSubscribers\SwaggerSaveDocumentationSubscriber;
9+
use RonasIT\AutoDoc\Support\PHPUnit\EventSubscribers\SwaggerSaveDocumentationSubscriber;
1010

1111
final class SwaggerExtension implements PhpunitExtension
1212
{

‎src/Tests/AutoDocTestCaseTrait.php‎ renamed to ‎src/Traits/AutoDocTestCaseTrait.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<?php
22

3-
namespace RonasIT\AutoDoc\Tests;
3+
namespace RonasIT\AutoDoc\Traits;
44

55
use RonasIT\AutoDoc\Http\Middleware\AutoDocMiddleware;
66

0 commit comments

Comments
 (0)