README

Proper Lad（Proper Laravel API Documenter）提供了一种生成API文档的简便方法。

如果你的代码编写得很好，你会喜欢Proper LAD。

Proper LAD以一种非常智能的方式生成文档（所以你不需要）

加载Router添加的所有路由（在你的 web.php 和 api.php 文件中...参见 Laravel路由）
过滤掉你想文档化的路由；通过中间件（例如 api 或 web）或通过前缀（例如 api/1.0 或 oauth）...或两者都过滤
加载路由对应的控制器类，以及它的PHP DocBlock，加载任何定义的@tags
加载路由对应的（控制器）函数，以及它的PHP DocBlock，加载任何定义的@tags
加载传递给函数调用的自定义请求
加载在自定义请求中使用的验证规则
加载在PHP DocBlock中找到的响应@return类型
使用Laravel的Model Factories模拟响应或从预定义示例中加载它
加载分配给路由的中间件名称，用于解释路由限制/限制/其他
并渲染一个整洁的文档模板 + 如果你想自定义文档范式，还有很多其他功能。

享受吧！

欢迎为此仓库做出贡献，并将得到完全认可。有关更多信息，请查看contributing.md以查看待办事项列表。

安装

通过Composer安装，请运行

composer require doge-dev/laravel-api-documenter

在添加包后，如果你想要发布配置文件、文本和视图，请运行 vnedor:publish

php artisan vendor:publish

并从下拉列表中选择 doge-dev/laravel-api-documenter

配置

运行 php artisan vendor:publish 后，在你的配置目录中会创建一个名为 laravel-api-documenter.php 的配置文件。

这里可以设置一些东西，这样你就不需要根据具体情况设置了

view-template 决定了用于渲染HTML 的默认模板
描述确定用于描述在自定义请求中发现的验证规则的默认翻译文件。
示例确定用于存储 @return 示例的默认翻译文件。
前缀列出用于过滤路由的默认前缀。
中间件 列出用于过滤路由的默认中间件。

用法

您可以从代码生成文档的几种方法。

正确的LAD（Laravel API Documenter）高度可自定义和调整，以适应您喜欢的文档模式。这些功能将在自定义部分进行讨论。

使用路由

生成文档的最简单方法是简单地添加一个路由并渲染blade模板。

Route::get('api-documentation', function () {

    $documenter = new \DogeDev\LaravelAPIDocumenter\LaravelAPIDocumenter();

    return $documenter->getView();
});

使用Artisan

您可以通过 artisan 命令将HTML文件生成到您选择的路由。

php artisan doge-dev:generate-documentation

注意： 如果您运行带有 --help 的命令，您将获得运行控制台命令的所有选项列表。

使用Proper LAD

Proper LAD DogeDev\LaravelAPIDocumenter\LaravelAPIDocumenter 使用了几个函数来完成这项工作，您可以使用这些函数。

getRoutes();            // Gets a collection of documented routes 
getView();              // Get the evaluated view contents for the API documentation view 
getHTML();              // Gets the string contents of the View
saveHTMLToFile($path);  // Saves the API documentation to a file

过滤路由

您可以选择仅记录某些路由。

您可以使用中间件过滤器仅过滤 api 路由，例如

$documenter->setMiddleware(['api', 'some-other-middleware-name'])->getRoutes()

或者，您可以使用前缀过滤路由

$documenter->setPrefix(['oauth', 'api/1.0'])->getRoutes()

分组路由

Proper LAD 使用 Collections，因此对路由进行排序、分组和转换应该是相当直接的。

例如，您可以使用控制器DocBlock中的 @title 标签对路由进行分组

$routes = $documenter->getRoutes()->groupBy(function($route) {

    if ($route->controller) {

        if ($route->controller->comment->tags->where('type', '@title')->isNotEmpty()) {

            return $route->controller->comment->tags->where('type', '@title')->first()->value;
        }
    }

    return 'Undefined';
});

或者，您可以简单地按控制器名称对它们进行排序

$routes = $documenter->getRoutes()->groupBy('controller.name');

自定义

创建自定义验证描述

所有验证规则都存储在LAD的 descriptions 翻译文件中。

LAD使用与Laravel几乎相同的字符串来描述验证约束，但是它们略有调整以适应目的（记录需求而不是报告验证错误）。

如果您有自定义验证规则，您应该在位于资源供应商文件夹中的 descriptions.php 翻译文件中添加描述字符串。

'same' => 'The :attribute and :other must match.'

:attribute 参数将被正在验证的属性名称替换。

如果字符串中有更多的 :whatever 占位符，它们将被验证参数替换。

创建硬编码的响应示例

默认情况下，Proper LAD解析控制器函数的 @response 标签，并尝试使用 Laravel的模型工厂模拟响应对象。

但是，您也可以选择将响应写成纯文本。这可以通过向位于资源供应商文件夹中的 examples.php 翻译文件（位于资源 -> 供应商文件夹）中添加示例来实现。

\App\Some\Class::class => [
        "objectData" => [
            "foo" => "bar"
        ],
        "arrayData" => [1,2,3,4],
        "number" => 1,
        "boolean" => true,
    ],

因此，每当在响应中找到 \App\Some\Class 类时，就会使用列出的示例。

替换解析数据

通常您可能需要用自定义数据替换整个Route对象 - 例如，在记录Passports身份验证端点时。这可以通过将项目放入位于资源 -> 供应商文件夹中的 class-replacements.php 翻译文件（位于资源 -> 供应商文件夹）中轻松实现。

Proper LAD将解析路由，并用在 class-replacements 文件中找到的数据覆盖它。但是，它将保留任何未修改的属性。

[
    'Laravel\Passport\Http\Controllers\AuthorizationController@authorize' => [
        'function' => [
            'return' => [
                'example' => [
                    'token'      => 'some-realy-long-token',
                    'expires-in' => 3423452345423,
                ],
            ],
        ],
    ],
]

通过添加此行，您将有效地替换此控制器解析数据的示例属性，其余数据将保持不变。

选择自定义视图模板

默认情况下，Prope LAD使用随LAD一起提供的默认blade模板。

模板处理了很多情况，其中数据缺失，我们强烈建议探索模板以及LAD用于渲染模板的对象。

通过熟悉数据，您可以轻松开发自己的文档模式，并轻松编写用于渲染它的模板。

您可以选择使用不同的blade模板来渲染HTML。

$documenter->setViewTemplate('pages.index')->getView()

或者如果您在一个单页应用中实施此功能，您可以通过AJAX直接返回路由对象。

$documenter->getRoutes();

路由对象

这就是一个单页应用的正确LAD路由对象的外观。

{#4628 ▼
  +"uri": "api/1.1/logout"         // API route
  +"name": null                    // Named route [https://laravel.net.cn/docs/5.7/routing#named-routes]
  +"methods": Collection {#4615 ▼  // List of accepted HTTP methods
    #items: array:1 [▼
      0 => "POST"
    ]
  }
  +"middleware": {#4616 ▼            // List of Middleware used
    +"names": Collection {#4612 ▼    // Names of middleware groups
      #items: array:3 [▼
        0 => "api"
        1 => "least_supported_api_version"
        2 => "auth:api"
      ]
    }
    +"classes": Collection {#4618 ▼  // List of middleware classes used
      #items: array:5 [▼
        0 => "Illuminate\Routing\Middleware\ThrottleRequests:60,1"
        1 => "Illuminate\Auth\Middleware\Authenticate:api"
        2 => "Illuminate\Routing\Middleware\SubstituteBindings"
        3 => "App\Http\Middleware\LogsAPIIP"
        4 => "App\Http\Middleware\LeastSupportedApiVersion"
      ]
    }
  }
  +"controller": {#4623 ▼                                 // The Controller object
    +"name": "App\Http\Controllers\Auth\LoginController"  // Name of the Controller 
    +"comment": {#4622 ▼                                  // The Docblock comment object
      +"text": "Class LoginController"                    // ... text of the comment
      +"tags": Collection {#4621 ▼                        // ... tags found in the docblock
        #items: array:2 [▼
          0 => {#4620 ▼
            +"type": "@package"                             // ... type of the tag
            +"value": "App\Http\Controllers\Auth"           // ... value for the tag
          }
          1 => {#4614 ▼
            +"type": "@title"                               // ... type of the tag
            +"value": "Login"                               // ... value for the tag
          }
        ]
      }
      +"original": """                                    // ... original docblock that was parsed 
        /**\n
         * Class LoginController\n
         *\n
         * @package App\Http\Controllers\Auth\n
         * @title Login\n
         */
        """
    }
  }
  +"function": {#4629 ▼                     // The Controllers function object
    +"name": "apiLogout"                    // Name of the function
    +"comment": {#4627 ▼                    // The PHP Docblock Comment object
      +"text": "API Logout function"
      +"tags": Collection {#4626 ▼
        #items: array:2 [▼
          0 => {#4624 ▼
            +"type": "@param"
            +"value": "Request $request"
          }
          1 => {#4625 ▼
            +"type": "@return"
            +"value": "boolean"
          }
        ]
      }
      +"original": """
        /**\n
             * API Logout function\n
             *\n
             * @param Request $request\n
             *\n
             * @return boolean\n
             */
        """
    }
    +"request": null                        // Custom Request object used in the Controlller function
    +"return": Collection {#4633 ▼          // Return value
      #items: array:1 [▼
        0 => {#4634 ▼
          +"type": "boolean"                // ... return type
          +"object": null                   // ... return Object
          +"example": null                  // ... return example
          +"text": null                     // ... reutrn text
        }
      ]
    }
  }
  +"errors": Collection {#4631 ▼            // errors found on route
    #items: []
  }
  +"warnings": Collection {#4630 ▼          // warnings found on route
    #items: array:1 [▼
      0 => "Custom request not found"
    ]
  }
}

变更日志

有关最近更改的更多信息，请参阅变更日志。

测试

迄今为止还没有进行任何测试。我们鼓励您通过编写测试来贡献：）

贡献

有关详细信息以及待办事项列表，请参阅contributing.md。

安全性

如果您发现任何与安全相关的问题，请通过电子邮件marko@dogedev.com联系，而不是使用问题跟踪器。

致谢

许可

MIT。有关更多信息，请参阅许可文件。

doge-dev / laravel-api-documenter

维护者

详细信息