Package Data | |
---|---|
Maintainer Username: | iMetal |
Package Create Date: | 2022-10-25 |
Package Last Update: | 2023-05-17 |
Home Page: | https://imetal.nl |
Language: | PHP |
License: | MIT |
Last Refreshed: | 2025-02-16 03:01:03 |
Package Statistics | |
---|---|
Total Downloads: | 804 |
Monthly Downloads: | 0 |
Daily Downloads: | 0 |
Total Stars: | 0 |
Total Watchers: | 0 |
Total Forks: | 1 |
Total Open Issues: | 0 |
This plugin is designed to generate documentation for your REST API during the passing PHPUnit tests.
Install the package using the following command: composer require imetal/lumen-swagger
Note
For Laravel 5.5 or later the package will be auto-discovered. For older versions add the
AutoDocServiceProvider
to the providers array inconfig/app.php
as follow:'providers' => [ // ... RonasIT\Support\AutoDoc\AutoDocServiceProvider::class, ],
Run php artisan vendor:publish
Add \RonasIT\Support\AutoDoc\Http\Middleware\AutoDocMiddleware::class
middleware to the global HTTP middleware stack in Http/Kernel.php
.
Add \RonasIT\Support\AutoDoc\Tests\AutoDocTestCaseTrait
trait to tests/TestCase.php
Configure documentation saving using one of the next ways:
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)
<extensions>
<extension class="RonasIT\Support\AutoDoc\Tests\PhpUnitExtensions\SwaggerExtension"/>
</extensions>
<testsuites>
<testsuite name="Feature">
<directory suffix="Test.php">./tests/Feature</directory>
</testsuite>
</testsuites>
php artisan swagger:push-documentation
console command after
the tests
stage in your CI/CD configurationCreate test for API endpoint:
public function testUpdate()
{
$response = $this->json('put', '/users/1', [
'name': 'Updated User',
'is_active': true,
'age': 22
]);
$response->assertStatus(Response::HTTP_NO_CONTENT);
}
Create request class:
<?php
namespace App\Http\Requests;
use Illuminate\Foundation\Http\FormRequest;
/**
* @summary Update user
*
* @description
* This request should be used for updating the user data
*
* @_204 Successful
*
* @is_active will indicate whether the user is active or not
*/
class UpdateUserDataRequest extends FormRequest
{
/**
* Determine if the user is authorized to make this request.
*
* @return bool
*/
public function authorize()
{
return true;
}
/**
* Validation Rules
*
* @return array
*/
public function rules()
{
return [
'name' => 'string',
'is_active' => 'boolean',
'age' => 'integer|nullable'
];
}
}
Note
For correct working of plugin you'll have to dispose all the validation rules in the
rules()
method of your request class. Also, your request class must be connected to the controller via dependency injection. Plugin will take validation rules from the request class and generate fields description of input parameter.
Run tests
Go to route defined in the auto-doc.route
config
Profit!
You can use the following annotations in your request classes to customize documentation of your API endpoints:
Note
If you do not use request class, the summary and description and parameters will be empty.
auto-doc.route
- route for generated documentationauto-doc.basePath
- root of your APIYou can specify the way to collect documentation by creating your own custom driver.
You can find example of drivers here.
Thank you for considering contributing to Lumen Swagger plugin! The contribution guide can be found in the Contributing guide.
Lumen Swagger plugin is open-sourced software licensed under the MIT license.