README

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

关于

此包受到了 darki73/laravel-swagger 和 kevupton/laravel-swagger 的极大启发。
使用方式与 mtrajano/laravel-swagger 非常相似，不同之处在于

1. OAS3 支持
2. 自定义装饰器
3. 自定义响应
4. 自动生成（假设已启用相关配置选项）
5. 包含 Swagger UI
6. 模型生成
7. 基于路由前缀或控制器名称生成操作标签

安装

通过 composer 安装包

composer require aluisio-pires/laravel-swagger-docs

发布配置文件和视图

php artisan vendor:publish --provider "AluisioPires\SwaggerDocs\SwaggerServiceProvider"

编辑 swagger.php 配置文件以满足您的需求

使用方法

Laravel Swagger Docs 基于Laravel推荐的实践。它将解析您的路由并为每个路由生成一个路径对象。如果您在控制器的操作中注入了表单请求类作为请求验证，它还会为具有它们的每个请求生成参数。对于参数，它将考虑请求是GET/HEAD/DELETE还是POST/PUT/PATCH请求，并尽可能猜测应该生成哪种参数对象类型。它还将生成路径参数，如果您的路由包含它们。最后，此包还将扫描您的操作方法中的任何文档，并将其作为摘要和描述添加到该路径中，同时添加任何适当的注释，如@deprecated。

需要注意的是，此库倾向于明确性。即使有默认值，它也会选择包含键。例如，它选择说明路由的 deprecated 值为 false，而不是省略它。我认为这通过不省略重要信息使阅读文档变得更加容易。如果用户选择省略默认值，文件可以很容易地进行清理。

命令行

生成 Swagger 文档非常简单，只需在项目根目录中运行 php artisan swagger:generate 即可。命令的输出将存储在配置文件中链接的存储路径。

如果您希望为路由的子集生成文档，可以使用 --filter 参数传递过滤器，例如：php artisan swagger:generate --filter="/api"

您还可以配置 swagger.php 文件，以便在访问 Swagger UI 时始终生成模式，或者只需在 .env 文件中添加此行：SWAGGER_GENERATE_ALWAYS=true

默认情况下，laravel-swagger 以 JSON 格式打印文档。如果您想以 YAML 格式，可以使用 --format 标志覆盖格式。如果选择这样做，请确保已安装 yaml 扩展。

格式选项是：json yaml

@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 装饰器

• 必须提供 code 属性，并且必须是属性列表中的第一个
• 您可以使用可选的 description 属性来描述您的响应
• 您可以使用可选的ref属性来引用一个模型，您也可以将该模型包裹在[]中以引用该模型的数组，或者在内部使用完整的模型路径，最后您可以使用模式构建器。

/**
* @Response({
*     code: 200
*     description: return user model
*     ref: User
* })
* @Response({
*     code: 400
*     description: Bad Request, array of APIError model
*     ref: [APIError]
* })
* @Response({
*     code: 302
*     description: Redirect
* })
* @Response({
*     code: 500
*     description: Internal Server Error
* })
*/
public function someMethod(Request $request) {}

/**
 * You can also refer object directly
 * 
 * 
 * @Response({
 *     code: 200
 *     description: direct user model reference
 *     ref: #/components/schemas/User
 * })
 */
public function someMethod2(Request $request) {}

/**
 * Using P schema builder for Laravel Pagination
 * 
 * @Response({
 *     code: 200
 *     description: a laravel pagination instance with User model
 *     ref: P(User)
 * })
 */
public function someMethod3(Request $request) {}

注意：您可以查看所有可用的模式构建器或创建自己的模式构建器，通过探索swagger.schema_builders配置来获取更多信息。

自定义验证器

这些验证器完全是出于视觉目的，然而，其中一些实际上可以进行验证。

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