Skip to content

Commit 63a9c45

Browse files
committed
Update README.md
1 parent 71ecb3e commit 63a9c45

File tree

1 file changed

+21
-27
lines changed

1 file changed

+21
-27
lines changed

readme.md renamed to README.md

+21-27
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,11 @@ passing PHPUnit tests.
2828

2929
## Installation
3030

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+
```
3236

3337
> ***Note***
3438
>
@@ -43,45 +47,39 @@ passing PHPUnit tests.
4347
> ],
4448
> ```
4549
46-
2. Run `php artisan vendor:publish --provider=RonasIT\\AutoDoc\\AutoDocServiceProvider`
50+
1. Run `php artisan vendor:publish --provider=RonasIT\\AutoDoc\\AutoDocServiceProvider`
4751
1. Add `\RonasIT\AutoDoc\Http\Middleware\AutoDocMiddleware::class` middleware to the global HTTP middleware list `bootstrap\app.php`:
4852
4953
```php
5054
return Application::configure(basePath: dirname(__DIR__))
5155
->withMiddleware(function (Middleware $middleware) {
5256
$middleware->use([
53-
...
57+
//...
5458
\RonasIT\AutoDoc\Http\Middleware\AutoDocMiddleware::class,
5559
]);
5660
});
5761
```
5862
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
6064
1. Configure documentation saving using one of the next ways:
6165
- 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)**
6466

6567
```xml
6668
<phpunit>
69+
//...
6770
<extensions>
6871
<bootstrap class="RonasIT\AutoDoc\Support\PHPUnit\Extensions\SwaggerExtension"/>
6972
</extensions>
70-
<testsuites>
71-
<testsuite name="Feature">
72-
<directory suffix="Test.php">./tests/Feature</directory>
73-
</testsuite>
74-
</testsuites>
7573
</phpunit>
7674
```
7775
- Call `php artisan swagger:push-documentation` console command after
78-
the `tests` stage in your CI/CD configuration
76+
the `tests` stage.
7977

8078
## Usage
8179

8280
### Basic usage
8381

84-
1. Create request class:
82+
1. Create a request class:
8583

8684
```php
8785
<?php
@@ -130,6 +128,7 @@ passing PHPUnit tests.
130128
}
131129

132130
```
131+
133132
> ***Note***
134133
>
135134
> For correct working of plugin you'll have to dispose all the validation rules
@@ -138,7 +137,7 @@ passing PHPUnit tests.
138137
> Plugin will take validation rules from the request class and generate fields description
139138
> of input parameter.
140139

141-
2. Create a controller and a method for your route:
140+
1. Implement request handling in the corresponding controller class:
142141

143142
```php
144143
<?php
@@ -160,10 +159,10 @@ passing PHPUnit tests.
160159

161160
> ***Note***
162161
>
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.
165164

166-
3. Create test for API endpoint:
165+
3. Create a test for the API endpoint:
167166

168167
```php
169168
public function testUpdate()
@@ -178,15 +177,15 @@ passing PHPUnit tests.
178177
}
179178
```
180179

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
183182
6. Profit!
184183

185184
![img.png](resources/assets/images/img.png)
186185

187186
### Annotations
188187

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:
190189

191190
- **@summary** - short description of request
192191
- **@description** - implementation notes
@@ -198,11 +197,6 @@ You can use the following annotations in your request classes to customize docum
198197
>
199198
> If you do not use request class, the summary and description and parameters will be empty.
200199

201-
### Configs
202-
203-
- `auto-doc.route` - route for generated documentation
204-
- `auto-doc.basePath` - root of your API
205-
206200
### Custom driver
207201

208202
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
212206
### Viewing OpenAPI documentation
213207

214208
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.
217211

218212
### Merging additional documentations
219213

0 commit comments

Comments
 (0)