README

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

关于

此软件包深受 Mezatsong/laravel-swagger-docs 的启发。

此软件包包含以下功能

1. OAS3 支持（带有常量验证以确保语法和兼容性）
2. 自定义装饰器
3. 自定义响应
4. 自定义模式
5. 自定义模式构建器
6. 基于路径和表单请求类自动生成参数
7. 包含 Swagger UI，可选不同的 UI 驱动程序
8. 自动通过模型或自定义模式类生成模式
9. 根据路由前缀或控制器的名称生成操作标签

安装

通过 composer 安装包

composer require savionicodemos/laravel-auto-swagger --dev

发布配置文件和视图

php artisan vendor:publish --provider "AutoSwagger\Docs\SwaggerServiceProvider"

编辑 swagger.php 配置文件以适应您的喜好

使用方法

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

注释语法

注释以控制器方法的 PHPDoc 块中的语法编写。语法如下

/**
 * @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"]
 * })
 * 
 */

语法基本上是注释块中的 JSON。请注意，必须严格遵循 JSON 语法。

规则

• key: value 对必须由列 : 分隔
• key: value 对必须始终在同一行上。如果您想写更长的描述，可以在注释本身中编写，此描述将用作路由的描述。您可以在 @Request() 装饰器中看到示例。
• 当你需要使用数组时，可以使用与JSON相同的方括号[]来定义它。

@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", // <- If you add here, this will overwrite the summary from above.
*     "description": "A short description", // <- If you need a longer one, just use the comment itself
*     "tags": ["Authentication","Users"] // <- This Request will be used in this two tags section
* })
*/
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",
*     "ref": "APIError[]" // <- An Array of APIError, can be a custom Schema
* })
* @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" // <- Full Schema path
 * })
 */
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)" // <- Using Schema Builder
 * })
 */
public function someMethod3(Request $request) {}

注意

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

自定义验证器

这些验证器纯粹是为了视觉目的而制作的，然而，其中一些实际上可以进行验证。但是应该放在哪里呢？你可以在表单请求类的 rules 数组中像正常Laravel验证一样简单地插入它。

swagger_default

它设置文档中参数的默认值。

$rules = [
    'locale'        =>  'swagger_default:en_GB'
];

swagger_example

它设置文档中参数的示例值。

$rules = [
    'currency'        =>  'swagger_example:EUR'
];

注意

swagger_default 和 swagger_example 之间的区别在于，swagger_default 将通知用户此值是该参数在应用程序中的默认值。而 swagger_example 只会展示如何填充参数的一个示例。

swagger_description

它设置文档中参数的描述。

$rules = [
    'limit'         =>  'swagger_description:Limit the number of items to return'
];

swagger_min

$rules = [
    // This will simply display the 'minimum' value in the documentation
    'page'          =>  'swagger_default:1|swagger_min:1', 
    // This will also fail if the `page` parameter will be less than 1
    'page'          =>  'swagger_default:1|swagger_min:1:fail'
];

swagger_max

$rules = [
    // This will simply display the 'maximum' value in the documentation
    'take'          =>  'swagger_default:1|swagger_min:1|swagger_max:50',
    // This will also fail if the `take` parameter will be greater than 50
    'take'          =>  'swagger_default:1|swagger_min:1|swagger_max:50:fail'
];