freedomcore / laravel-swagger
Swagger documentation generator for Laravel
Requires
Requires (Dev)
- php: ^7.3
- laravel/passport: ^10.0
- orchestra/testbench: ^6.2.0
- phpunit/phpunit: ^9.3
Suggests
- ext-yaml: Required to generate YAML
README
Simple to use OAS3 compatible documentation generator.
Also includes Swagger UI.
About
This package is heavily inspired by the mtrajano/laravel-swagger and DarkaOnLine/L5-Swagger.
Usage is pretty similar to the mtrajano/laravel-swagger
with the difference being:
- OAS3 support
- "Custom decorators" inspired by Nest.JS
- Automatic generation (assuming relevant configuration option is turned on)
- Inclusion of Swagger UI
I've spent a couple of hours making this package to suit my needs, and it does so far.
All I am trying to say is - I don't think I will be actively maintaining this package unless people will have interest in it.
Requirements
This package developed on Laravel 8.11.2
, but it might work on the previous releases.
All other requirements are inherited from the Laravel 8
.
Installation
Install package through composer
composer require freedomcore/laravel-swagger
Publish configuration files and views
php artisan vendor:publish --provider "FreedomCore\Swagger\SwaggerServiceProvider"
Edit the swagger.php
configuration file for your liking
Usage
@Request() decorator
You can have only one @Request()
decorator.
/** * You can also do this, first line will be "summary" * * And anything 1 * apart from the "summary" will count as "description" * * @Request({ * summary: Title of the route, * description: This is a longer description for the route which will be visible once the panel is expanded, * tags: Authentication,Users * }) */ public function someMethod(Request $request) {}
@Response() decorator
You can have multiple @Response
decorators
/** * @Response({ * code: 302 * description: Redirect * }) * @Response({ * code: 400 * description: Bad Request * }) * @Response({ * code: 500 * description: Internal Server Error * }) */ public function someMethod(Request $request) {}
Custom Validators
These validators are made purely for visual purposes, however, some of them can actually do validation
swagger_default
$rules = [ 'locale' => 'swagger_default:en_GB' ];
swagger_min
$rules = [ 'page' => 'swagger_default:1|swagger_min:1', // This will simply display the 'minimum' value in the documentation 'page' => 'swagger_default:1|swagger_min:1:fail' // This will also fail if the `page` parameter will be less than 1 ];
swagger_max
$rules = [ 'take' => 'swagger_default:1|swagger_min:1|swagger_max:50', // This will simply display the 'maximum' value in the documentation 'take' => 'swagger_default:1|swagger_min:1|swagger_max:50:fail' // This will also fail if the `take` parameter will be greater than 50 ];