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 文件中更改。

参数

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

当添加一个参数时，它将自动包含在相应的 操作 中。例如，要将 "id" 参数添加到 "example" 路径和 "show" 操作中，请使用以下命令：

# 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`

此路由和操作的文件夹结构如下：

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

注意事项

同一文件中不能有两个使用相同方法的 操作（例如，index 和 show）。它们需要位于单独的文件中。

操作

• 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= 参数指定，并且与 操作 的指定顺序相同。

如果未指定名称，文件将使用对应的 操作 名称。

更新说明

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

命令

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

php artisan docs:note nome

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

php artisan docs:note nome --routes=2

兼容性

Laravel - 9.19 或更高版本