README

简单易用的 OAS3 兼容文档生成器。
还包括 Swagger UI。

关于

本包深受 mtrajano/laravel-swagger 和 DarkaOnLine/L5-Swagger 的启发。
使用方式与 mtrajano/laravel-swagger 类似，但有以下区别：

1. OAS3 支持
2. 受 Nest.JS 启发的“自定义装饰器”
3. 自动生成（假设已开启相关配置选项）
4. 包含 Swagger UI

我花费了几个小时制作这个包来满足我的需求，到目前为止它已经做到了。
我只想说 - 除非人们对这个包感兴趣，否则我不认为我会积极维护它。

要求

本包基于 Laravel 8.11.2 开发，但可能也适用于之前的版本。
所有其他要求继承自 Laravel 8。

安装

通过 composer 安装包

composer require freedomcore/laravel-swagger

发布配置文件和视图

php artisan vendor:publish --provider "FreedomCore\Swagger\SwaggerServiceProvider"

根据您的喜好编辑 swagger.php 配置文件

使用

@Request() 装饰器

您只能有一个 @Request() 装饰器。

/**
* 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() 装饰器

您可以有多个 @Response 装饰器

/**
* @Response({
*     code: 302
*     description: Redirect
* })
* @Response({
*     code: 400
*     description: Bad Request
* })
* @Response({
*     code: 500
*     description: Internal Server Error
* })
*/
public function someMethod(Request $request) {}

自定义验证器

这些验证器纯粹为了视觉效果，但实际上一些可以进行验证

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
];