Skip to content

Commit 9db0443

Browse files
astorozhevskyastorozhevsky
authored
Merge pull request #63 from RonasIT/evikulov/readme-update
Evikulov/readme update
2 parents c2ae22e + 00e2a3f commit 9db0443

File tree

3 files changed

+146
-116
lines changed

3 files changed

+146
-116
lines changed

‎assets/images/img.png‎

71.3 KB
Loading

‎assets/images/laravel-banner.png‎

602 KB
Loading

‎readme.md‎

Lines changed: 146 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -1,130 +1,160 @@
1-
# Laravel Swagger plugin
1+
# Laravel Swagger plugin
2+
23
<p align="left">
34
<a href="https://packagist.org/packages/ronasit/laravel-swagger"><img src="https://img.shields.io/packagist/dt/ronasit/laravel-swagger" alt="Total Downloads"></a>
45
<a href="https://packagist.org/packages/ronasit/laravel-swagger"><img src="https://img.shields.io/packagist/v/ronasit/laravel-swagger" alt="Latest Stable Version"></a>
56
<a href="https://packagist.org/packages/ronasit/laravel-swagger"><img src="https://img.shields.io/packagist/l/ronasit/laravel-swagger" alt="License"></a>
67
</p>
78

9+
![img.png](assets/images/laravel-banner.png)
10+
811
## Introduction
9-
This plugin is designed to generate documentation about your Rest API while
10-
passing the tests. Special Middleware installed on the Route generates
11-
Swagger-file after the successful completion of all tests. In addition, this
12-
plugin is able to draw Swagger-template to display the generated documentation for a config.
12+
13+
This plugin is designed to generate documentation for your REST API during the
14+
passing PHPUnit tests.
15+
1316
## Installation
1417

15-
### Composer
16-
1. Require this package with composer using the following command: `composer require ronasit/laravel-swagger`
17-
18-
### Laravel
19-
1. For Laravel 5.5 or later the package will be auto-discovered.
20-
For older versions add the `AutoDocServiceProvider` to the providers array in config/app.php as follow:
21-
```php
22-
'providers' => [
23-
// ...
24-
RonasIT\Support\AutoDoc\AutoDocServiceProvider::class,
25-
],
26-
```
27-
2. To publish configuration file run `php artisan vendor:publish`
28-
### Plugin
29-
1. Add middleware **\RonasIT\Support\AutoDoc\Http\Middleware\AutoDocMiddleware::class** to *Http/Kernel.php*.
30-
1. Use **\RonasIT\Support\AutoDoc\Tests\AutoDocTestCaseTrait** in your TestCase in *tests/TestCase.php*
31-
1. In *config/auto-doc.php* you can specify enabling of plugin, project info,
32-
some default descriptions and routes for documentation rendering.
33-
1. In *.env* file you should add following lines:
34-
`
35-
LOCAL_DATA_COLLECTOR_PROD_PATH=/example-folder/documentation.json
36-
LOCAL_DATA_COLLECTOR_TEMP_PATH=/tmp/documentation.json
37-
`
38-
1. Configure documentation saving using one of the next ways:
39-
- Add `SwaggerExtension` to the `<extensions>` block of your `phpunit.xml`. Please note that this way will be removed after updating PHPUnit up to 10 version (https://github.com/sebastianbergmann/phpunit/issues/4676)
40-
```
41-
<extensions>
42-
<extension class="RonasIT\Support\AutoDoc\Tests\PhpUnitExtensions\SwaggerExtension"/>
43-
</extensions>
44-
<testsuites>
45-
<testsuite name="Feature">
46-
<directory suffix="Test.php">./tests/Feature</directory>
47-
</testsuite>
48-
</testsuites>
49-
```
50-
- Call `php artisan swagger:push-documentation` console command after the `tests` stage in your CI/CD configuration
51-
52-
## Usages
53-
For correct working of plugin you have to dispose all the validation rules in the rules() method of `YourRequest` class,
54-
which must be connected to the controller via DependencyInjection. In annotation of custom request you can specify
55-
summary and description. Plugin will take validation rules from your request and use it as description
56-
of input parameter.
57-
58-
### Example
59-
60-
```php
61-
<?php
62-
63-
namespace App\Http\Requests;
64-
65-
use Illuminate\Foundation\Http\FormRequest;
66-
67-
/**
68-
* @summary Updating of user
69-
*
70-
* @description
71-
* This request mostly needed to specity flags <strong>free_comparison</strong> and
72-
* <strong>all_cities_available</strong> of user
73-
*
74-
* @_204 Successful MF!
75-
*
76-
* @some_field Description of this field from the rules method
77-
*/
78-
class UpdateUserDataRequest extends FormRequest
79-
{
80-
/**
81-
* Determine if the user is authorized to make this request.
82-
*
83-
* @return bool
84-
*/
85-
public function authorize()
86-
{
87-
return true;
88-
}
18+
1. Install the package using the following command: `composer require ronasit/laravel-swagger`
19+
20+
> ***Note***
21+
>
22+
> For Laravel 5.5 or later the package will be auto-discovered.
23+
> For older versions add the `AutoDocServiceProvider` to the
24+
> providers array in `config/app.php` as follow:
25+
>
26+
> ```php
27+
> 'providers' => [
28+
> // ...
29+
> RonasIT\Support\AutoDoc\AutoDocServiceProvider::class,
30+
> ],
31+
> ```
32+
33+
1. Run `php artisan vendor:publish`
34+
2. Add `\RonasIT\Support\AutoDoc\Http\Middleware\AutoDocMiddleware::class` middleware to the global HTTP middleware stack in `Http/Kernel.php`.
35+
3. Add `\RonasIT\Support\AutoDoc\Tests\AutoDocTestCaseTrait` trait to `tests/TestCase.php`
36+
4. Configure documentation saving using one of the next ways:
37+
- Add `SwaggerExtension` to the `<extensions>` block of your `phpunit.xml`.
38+
**Please note that this way will be removed after updating**
39+
**PHPUnit up to 10 version (https://github.com/sebastianbergmann/phpunit/issues/4676)**
40+
```xml
41+
<extensions>
42+
<extension class="RonasIT\Support\AutoDoc\Tests\PhpUnitExtensions\SwaggerExtension"/>
43+
</extensions>
44+
<testsuites>
45+
<testsuite name="Feature">
46+
<directory suffix="Test.php">./tests/Feature</directory>
47+
</testsuite>
48+
</testsuites>
49+
```
50+
- Call `php artisan swagger:push-documentation` console command after
51+
the `tests` stage in your CI/CD configuration
52+
53+
## Usage
54+
55+
### Basic usage
56+
57+
1. Create test for API endpoint:
58+
59+
```php
60+
public function testUpdate()
61+
{
62+
$response = $this->json('put', '/users/1', [
63+
'name': 'Updated User',
64+
'is_active': true,
65+
'age': 22
66+
]);
67+
68+
$response->assertStatus(Response::HTTP_NO_CONTENT);
69+
}
70+
```
71+
72+
2. Create request class:
73+
74+
```php
75+
<?php
76+
77+
namespace App\Http\Requests;
78+
79+
use Illuminate\Foundation\Http\FormRequest;
80+
81+
/**
82+
* @summary Update user
83+
*
84+
* @description
85+
* This request should be used for updating the user data
86+
*
87+
* @_204 Successful
88+
*
89+
* @is_active will indicate whether the user is active or not
90+
*/
91+
class UpdateUserDataRequest extends FormRequest
92+
{
93+
/**
94+
* Determine if the user is authorized to make this request.
95+
*
96+
* @return bool
97+
*/
98+
public function authorize()
99+
{
100+
return true;
101+
}
102+
103+
/**
104+
* Validation Rules
105+
*
106+
* @return array
107+
*/
108+
public function rules()
109+
{
110+
return [
111+
'name' => 'string',
112+
'is_active' => 'boolean',
113+
'age' => 'integer|nullable'
114+
];
115+
}
116+
}
117+
118+
```
119+
120+
> ***Note***
121+
>
122+
> For correct working of plugin you'll have to dispose all the validation rules
123+
> in the `rules()` method of your request class. Also, your request class
124+
> must be connected to the controller via [dependency injection](https://laravel.com/docs/9.x/container#introduction).
125+
> Plugin will take validation rules from the request class and generate fields description
126+
> of input parameter.
127+
128+
3. Run tests
129+
4. Go to route defined in the `auto-doc.route` config
130+
5. Profit!
89131
90-
/**
91-
* Get the validation rules that apply to the request.
92-
*
93-
* @return array
94-
*/
95-
public function rules()
96-
{
97-
return [
98-
'some_field' => 'string',
99-
'all_cities_available' => 'boolean',
100-
'free_comparison' => 'boolean'
101-
];
102-
}
103-
}
104-
105-
```
106-
107-
- **@summary** - short description of request
108-
- **@description** - Implementation Notes
109-
- **@_204** - Custom description of response code. You can specify any code as you want.
110-
- **@some_field** - Description of the field from the rules method
111-
112-
If you do not create a class Request, the summary, Implementation Notes and parameters will be empty.
113-
Plugin will collect codes and examples of responses only.
114-
115-
If you do not create annotations to request summary it will generate automatically from Name of Request.
116-
For example request **UpdateUserDataRequest** will have summary **Update user data request**.
117-
118-
If you do not create annotations for descriptions of codes it will be generated automatically the following priorities:
119-
1. Annotations of request
120-
2. Default description from *auto-doc.defaults.code-descriptions.{$code}*
121-
3. Descriptions from **Symfony\Component\HttpFoundation\Response::$statusTexts**
122-
123-
Note about configs:
124-
- *auto-doc.route* - it's a route for generated documentation
125-
- *auto-doc.basePath* - it's a root of your api root
132+
![img.png](assets/images/img.png)
133+
134+
### Annotations
135+
136+
You can use the following annotations in your request classes to customize documentation of your API endpoints:
137+
138+
- **@summary** - short description of request
139+
- **@description** - implementation notes
140+
- **@_204** - custom description of response code. You can specify any code as you want.
141+
- **@some_field** - description of the field from the rules method
126142
127-
Also you can specify way to collect documentation by creating your custom data collector class.
143+
> ***Note***
144+
>
145+
> If you do not use request class, the summary and description and parameters will be empty.
146+
147+
### Configs
148+
149+
- `auto-doc.route` - route for generated documentation
150+
- `auto-doc.basePath` - root of your API
151+
152+
### Custom driver
153+
154+
You can specify the way to collect documentation by creating your own custom driver.
155+
156+
You can find example of drivers [here](https://github.com/RonasIT/laravel-swagger/tree/master/src/Drivers).
157+
128158
## Contributing
129159
130160
Thank you for considering contributing to Laravel Swagger plugin! The contribution guide can be found in the [Contributing guide](CONTRIBUTING.md).

0 commit comments

Comments
 (0)