README

此包的目的是标准化项目路由的文档，并通过终端创建文档文件。创建的文件类型为 .yaml。

只需安装包并发布文件即可。

此包是为 Laravel 开发的，并基于 L5-Swagger 构建。

安装

请在终端中使用以下命令。

composer require labi9/elegan

安装包后，需要发布文件以使 Elegan 运作。请在终端中使用以下命令

php artisan vendor:publish --provider "Labi9\Elegan\EleganServiceProvider"

安装后

在浏览器中访问 http://127.0.0.1:8000/api/docs 路由，文档应如以下图片所示显示

配置

可以根据需要修改 config/elegan.php 和 config/l5-swagger.php 文件。

访问路由

要配置文档的访问路由，请进入 config/l5-swagger.php 文件并修改 api 的值。

// config/l5-swagger.php

'routes' => [
  'api' => 'novo/caminho'
]

阻止访问

安全中间件

在 Http/Kernel.php 文件中的 $routeMiddleware 变量中添加安全中间件。

// Http/Kernel.php

'access_docs' => \Labi9\Elegan\ValidateAccessEleganRoutes::class,

访问 config/l5-swagger.php 文件并添加中间件 access_docs。

// config/l5-swagger.php

'middleware' => [
  'api' => ['access_docs'],
],

配置提供者

访问 Providers/RouteServiceProvider.php 文件，并在 configureRateLimiting() 函数中添加以下代码

// Providers/RouteServiceProvider.php

RateLimiter::for('docs_ip_address', function (Request $request) {
  RateLimiter::hit($request->ip(), config('elegan.decay_minutes') * 60);

  return Limit::perMinutes(
    config('elegan.decay_minutes'),
    config('elegan.rate_limit')
  )->by($request->ip());
});

每分钟最大请求数和超时时间可以在 config/elegan.php 配置文件中调整。

访问路由

在 routes/web.php 路由文件中，添加对文档访问表单的访问路由

// routes/web.php

Route::middleware(['throttle:docs_ip_address'])->group(function () {
  Route::view('/access-docs', 'elegan.form')
    ->name('access-docs');
});

文档密钥

在 .env 文件中添加 ELEGAN_KEY 变量，该变量是文档的密码。

# .env

ELEGAN_KEY=chave_de_acesso

如果未添加 ELEGAN_KEY 变量，则默认密码为 elegan。

路由文件

默认情况下，.yaml 文件使用与 controller 方法名称（index、store、show、update 和 destroy）相同的名称。这些名称在本文档中被称为 Actions。

• index 和 show 使用 GET 方法
• store 使用 POST 方法
• update 使用 PUT 方法
• destroy 使用 DELETE 方法

每个 Action 都有其基于文件的默认配置。

注意：这些名称可以在 config/elegan.php 文件中更改。

命令

使用以下任一命令创建一个名为 actions.yaml 的文件，使用终端返回的路径作为路径区域的参考

基本命令

• php artisan docs:route example store 仅创建 store 文件。
• php artisan docs:route example index 仅创建 index 文件。
• php artisan docs:route example show 仅创建 show 文件。
• php artisan docs:route example update 仅创建 update 文件。
• php artisan docs:route example destroy 仅创建 destroy 文件。

# index.yaml

paths:
  /caminhoDaRota:
    $ref: example/actions.yaml

注意：actions.yaml 的名称可以在 config/elegan.php 文件中更改。

参数

要将参数添加到路由中，请使用":"字符后跟参数名称。可以在同一路由中添加多个参数。

添加参数后，它将自动包含在对应的action中。例如，要将"id"参数添加到"example"路由和"show"action中，请使用以下命令：

# show.yaml

php artisan docs:route example/:id show

该路由的文件夹结构如下所示

 ------------------
|- exemple
|-- id
|--- actions.yaml
|--- show.yaml
 ------------------

"id"参数将自动添加到show.yaml文件中，如下所示

parameters:
  - in: path
    name: id
    schema:
      type: string
    required: true
    description: ''

认证

在命令中添加--auth参数，表示该路由需要认证令牌。

php artisan docs:route example show --auth

security属性将自动添加到show.yaml文件中，如下所示

# show.yaml

security:
  - bearerAuth: []

完整命令

以下命令显示了docs:route的所有配置选项

php artisan docs:route example/:id index show store update destroy --auth`

该路由和action的文件夹结构如下所示

 ------------------
|- example
|-- id
|--- actions.yaml
|--- index.yaml
|--- store.yaml
|--- show.yaml
|--- update.yaml
|--- destroy.yaml
 ------------------

注意事项

在同一actions.yaml文件中不能有两个具有相同方法的Actions（例如，index和show）。它们需要放在单独的文件中。

Actions

• destroy生成一个具有DELETE方法的文件。
• show生成一个具有GET方法的文件。
• index生成一个具有GET方法和分页返回的文件。
• store生成一个具有POST方法和请求验证（需要手动添加）、请求示例和状态码201的文件。
• update生成一个具有PUT方法和请求验证（需要手动添加）、请求示例和状态码204的文件。

重命名yaml文件

• php artisan docs:route example/:id store --name=login生成一个具有POST方法，但文件名为login.yaml的文件。
• php artisan docs:route example/:id store show --name=login --name=me生成一个具有POST方法，但文件名为login.yaml的文件，以及一个具有GET方法，文件名为me.yaml的文件。

每个名称都必须使用--name=传递，并且与提供Actions的顺序相同。

如果没有提供名称，文件将使用对应的Action名称。

更新说明

更新说明用于存储文档的更新历史。

命令

要创建更新说明的基本结构，请使用以下命令

php artisan docs:note nome

如需描述更多路由，请使用--routes=number_of_routes参数，例如

php artisan docs:note nome --routes=2

兼容性

Laravel - 9.19或更高版本