README

自动从您的现有Laravel/Lumen/ Dingo 路由生成API文档。这里是输出示例。

php artisan apidoc:generate

注意：这是版本3的文档，与版本2有显著变化。如果您正在使用v2，可以在这里查看其文档这里。尽管如此，我们强烈建议您升级，因为v3更健壮，并修复了v2中的许多问题。

安装

注意：需要PHP 7和Laravel 5.5或更高版本。

$ composer require nickkuijpers/laravel-apidoc-generator

Laravel

通过运行以下命令发布配置文件：

php artisan vendor:publish --provider="Mpociot\ApiDoc\ApiDocGeneratorServiceProvider" --tag=apidoc-config

这将在您的 config 文件夹中创建一个 apidoc.php 文件。

Lumen

在您的 bootstrap/app.php 中注册服务提供者

$app->register(\Mpociot\ApiDoc\ApiDocGeneratorServiceProvider::class);

将配置文件从 vendor/mpociot/laravel-apidoc-generator/config/apidoc.php 复制到您的项目作为 config/apidoc.php。然后添加到您的 bootstrap/app.php

$app->configure('apidoc');

使用方法

在您生成文档之前，您需要在 config/apidoc.php 中配置一些内容。

output 这是生成文档将被写入的文件路径。默认：public/docs
postman 此软件包可以自动为您路由生成Postman集合，以及文档。此部分是您可以配置（或禁用）该功能的地方。
router 处理路由时要使用的路由器（可以是Laravel或Dingo。默认为 Laravel）
logo 您可以指定要在生成的文档中使用的自定义标志。将 logo 选项设置为指向您的标志文件的绝对路径。
routes 这是您指定要生成哪些规则文档的地方。您通过定义路由应该满足的条件和生成文档时应该应用的规则来指定要解析的路由。这些条件和规则在组中指定，允许您对不同路由应用不同的规则。

例如，假设您的配置如下所示

return [
     //...,
  
     'routes' => [
          [
              'match' => [
                  'domains' => ['*'],
                  'prefixes' => ['api/*', 'v2-api/*'],
                  'versions' => ['v1'],
              ],
              'include' => ['users.index', 'healthcheck*'],
              'exclude' => ['users.create', 'admin.*'],
              'apply' => [
                  'headers' => [
                      'Authorization' => 'Bearer: {token}',
                  ],
              ],
          ],
];

这意味着将生成所有域名（'*' 是通配符，表示任何字符）中的路由的文档，这些路由匹配任何 'api/*' 或 'v2-api/*' 模式，排除 'users.create' 路由和任何以 admin. 开头的路由，并包括 'users.index' 路由和任何以 healthcheck. 开头的路由。（除非您正在使用Dingo路由器，否则忽略 versions 键）。此外，在生成的文档中，这些路由将添加示例请求的标题 'Authorization: Bearer: {token}'。

您也可以将路由分开到不同的组中，以对它们应用不同的规则

<?php
return [
     //...,
  
     'routes' => [
          [
              'match' => [
                  'domains' => ['v1.*'],
                  'prefixes' => ['*'],
              ],
              'include' => [],
              'exclude' => [],
              'apply' => [
                  'headers' => [
                      'Token' => '{token}',
                      'Version' => 'v1',
                  ],
              ],
          ],
          [
              'match' => [
                  'domains' => ['v2.*'],
                  'prefixes' => ['*'],
              ],
              'include' => [],
              'exclude' => [],
              'apply' => [
                  'headers' => [
                      'Authorization' => 'Bearer: {token}',
                      'Api-Version' => 'v2',
                  ],
              ],
          ],
];

根据上述配置，v1.* 域名上的路由将应用 Token 和 Version 标题，而 v2.* 域名上的路由将应用 Authorization 和 Api-Version 标题。

注意：include 和 exclude 项是路由名的数组。支持通配符 *。注意：如果您正在使用DIngo路由器，则每个路由组必须要求 versions 参数。此参数不支持通配符。必须明确列出每个版本。

要生成API文档，请使用 apidoc:generate artisan命令。

$ php artisan apidoc:generate

它将使用您指定的配置生成文档。

记录您的API

此包使用以下资源生成API文档

分组端点

此包使用HTTP控制器文档块创建目录并显示API方法的描述。

在控制器文档块中使用@group会在API文档中创建一个分组。该控制器处理的所有路由都将在此分组下分组。在@group之后的简短描述应该是唯一的，以便允许锚点标签导航到此部分。可以包含一个更长的描述。还支持自定义格式化和<aside>标签。（请参阅Documentarian文档）

注意：使用@group是可选的。未分组的路由将放置在“通用”分组中。

在每个您希望在API文档中包含的方法上方，您应该有一个文档块。这应该包括一个唯一的简短描述作为第一项。可以添加一个可选的第二项，包含更多信息。两个描述将以不同的格式出现在API文档中，如下所示。您还可以为单个方法指定@group来覆盖控制器级别的分组定义。

/**
 * @group User management
 *
 * APIs for managing users
 */
class UserController extends Controller
{

	/**
	 * Create a user
	 *
	 * [Insert optional longer description of the API endpoint here.]
	 *
	 */
	 public function createUser()
	 {

	 }
	 
	/**
	 * @group Account management
	 *
	 */
	 public function changePassword()
	 {

	 }
}

结果

指定请求参数

要指定API路由接受的参数列表，请使用@bodyParam和@queryParam注解。

@bodyParam注解接受参数名称、其类型、可选的“required”标签，然后是其描述。
@queryParam注解接受参数名称、可选的“required”标签，然后是其描述

/**
 * @bodyParam title string required The title of the post.
 * @bodyParam body string required The title of the post.
 * @bodyParam type string The type of post to create. Defaults to 'textophonious'.
 * @bodyParam author_id int the ID of the author
 * @bodyParam thumbnail image This is required if the post type is 'imagelicious'.
 */
public function createPost()
{
    // ...
}

/**
 * @queryParam sort Field to sort by
 * @queryParam page The page number to return
 * @queryParam fields required The fields to include
 */
public function listPosts()
{
    // ...
}

它们将包含在生成的文档文本和示例请求中。

结果

注意：示例请求中的每个参数将使用随机值。如果您想指定示例值，可以在描述的末尾添加示例：your-example。例如

    /**
     * @queryParam location_id required The id of the location.
     * @queryParam user_id required The id of the user. Example: me
     * @queryParam page required The page number. Example: 4
     * @bodyParam user_id int required The id of the user. Example: 9
     * @bodyParam room_id string The id of the room.
     * @bodyParam forever boolean Whether to ban the user forever. Example: false
     */

注意：您还可以将@bodyParam注解添加到\Illuminate\Foundation\Http\FormRequest子类

/**
 * @bodyParam title string required The title of the post.
 * @bodyParam body string required The title of the post.
 * @bodyParam type string The type of post to create. Defaults to 'textophonious'.
 * @bodyParam author_id int the ID of the author
 * @bodyParam thumbnail image This is required if the post type is 'imagelicious'.
 */
class MyRequest extends \Illuminate\Foundation\Http\FormRequest
{

}

public function createPost(MyRequest $request)
{
    // ...
}

指示认证状态

您可以在方法上使用@authenticated注解来指示端点是否已认证。将在生成的文档中为该路由添加“需要认证”徽章。

提供示例响应

您可以提供路由的示例响应。这将在示例部分显示。有多种方法可以做到这一点。

@response

您可以通过使用包含有效JSON的@response注解为路由提供示例响应

/**
 * @response {
 *  "id": 4,
 *  "name": "Jessica Jones",
 *  "roles": ["admin"]
 * }
 */
public function show($id)
{
    return User::find($id);
}

此外，您还可以定义多个@response标签以及与特定响应相关的HTTP状态代码（如果没有设置状态代码，将返回200）

/**
 * @response {
 *  "id": 4,
 *  "name": "Jessica Jones",
 *  "roles": ["admin"]
 * }
 * @response 404 {
 *  "message": "No query results for model [\App\User]"
 * }
 */
public function show($id)
{
    return User::findOrFail($id);
}

@transformer, @transformerCollection, 和 @transformerModel

您可以使用@transformer标签（如果路由返回列表，则为@transformerCollection）定义用于路由结果的转换器。包将尝试使用以下步骤生成要转换的模型实例，并在第一个成功时停止

检查是否存在@transformerModel标签来定义正在转换的模型。如果没有，则使用转换器的transform()方法的第一个参数的类。
从Eloquent模型工厂获取模型的实例
如果参数是Eloquent模型，则从数据库中加载第一个。
使用new创建一个实例。

最后，它将模型传递给转换器，并显示该转换的结果作为示例响应。

例如

/**
 * @transformercollection \App\Transformers\UserTransformer
 * @transformerModel \App\User
 */
public function listUsers()
{
    //...
}

/**
 * @transformer \App\Transformers\UserTransformer
 */
public function showUser(User $user)
{
    //...
}

/**
 * @transformer \App\Transformers\UserTransformer
 * @transformerModel \App\User
 */
public function showUser(int $id)
{
    // ...
}

对于上面的第一条路由，此包将生成一组两个用户，然后将其通过转换器。对于最后两个，它将生成一个用户，然后通过转换器。

注意：为了支持转换器，您需要安装league/fractal包

composer require league/fractal

@responseFile

对于较大的响应体，您可能希望使用实际响应的转储。您可以将此响应放在您的Laravel存储目录中的文件（作为JSON字符串）中，并将其链接到它。例如，我们可以将此响应放在名为users.get.json的文件中，位于storage/responses

{"id":5,"name":"Jessica Jones","gender":"female"}

然后在您的控制器中，通过以下方式链接到它

/**
 * @responseFile responses/users.get.json
 */
public function getUser(int $id)
{
  // ...
}

该包将解析此响应，并在该路由的示例中显示。

类似于@response标签，您可以为响应提供多个@responseFile标签，并附带响应的HTTP状态码。

/**
 * @responseFile responses/users.get.json
 * @responseFile 404 responses/model.not.found.json
 */
public function getUser(int $id)
{
  // ...
}

自动生成响应

如果您没有使用上述任何方式指定示例响应，此包将尝试通过向路由发出请求（称为“响应调用”）来获取样本响应。关于响应调用的几点需要注意

它们是在数据库事务中完成的，之后更改将被回滚。
响应调用的配置位于config/apidoc.php中。它们在['apply']['response_calls']部分中为每个路由组进行配置，允许您为不同的一组路由应用不同的设置。
默认情况下，响应调用仅针对GET路由进行，但您可以进行配置。将methods键设置为方法数组的键或'*'以表示所有方法。将其保留为空数组以关闭该路由组的响应调用。
URL中的参数（例如：/users/{user}，/orders/{id?}）默认情况下将被替换为'1'。但是，您可以进行配置。将参数名称（包括花括号和问号）作为键，并将它们的替换值作为值放入bindings键。
您可以配置环境变量（这非常有用，可以防止触发外部服务，如通知）。默认情况下，APP_ENV设置为'documentation'。您可以在env键中添加更多变量。
默认情况下，该包将为您的文档化主体和查询参数生成虚拟值，并在请求中发送。（如果使用@bodyParam或@queryParam指定了示例值，则将使用这些值。）您可以在发送请求时配置应发送哪些头和附加查询和参数（分别通过headers、query和body键）。

Postman集合

生成器自动创建一个Postman集合文件，您可以将它导入到您的Postman应用中使用，以便进行更简单的API测试和用法。

如果您不想创建Postman集合，请将postman配置选项设置为false。

添加到Postman集合中的默认基本URL将是在您的Laravel config/app.php文件中找到的。这可能是https://。如果您想更改此设置，可以直接更新URL或将此配置值链接到您的环境文件以使其更具灵活性（如下所示）

'url' => env('APP_URL', 'http://yourappdefault.app'),

如果您引用的是上面的环境设置，那么您应该确保您已经更新了您的.env文件以设置适当的APP_URL值。否则，您的Postman集合将使用默认值（http://yourappdefault.app）。

APP_URL=http://yourapp.app

修改生成的文档

如果您想修改生成的文档的内容，请直接编辑生成的index.md文件。此文件的默认位置是：public/docs/source/index.md。

编辑markdown文件后，使用apidoc:rebuild命令重新构建您的文档为静态HTML文件。

$ php artisan apidoc:rebuild

作为可选参数，您可以使用--location来告诉更新命令文档的位置。

如果您想重新生成文档，可以运行 generate 命令，您可以使用 force 选项强制重新生成现有/修改过的 API 路由。

自动在文档开头或结尾添加 Markdown

如果您希望每次生成文档时都自动添加相同的内容，可以在源文件夹中添加 prepend.md 和/或 append.md 文件，它们将被包含在生成的文档之上和之下。

文件位置

public/docs/source/prepend.md - 将添加在标题和文本信息之后
public/docs/source/append.md - 将添加在文档末尾。

进一步修改

本包使用 Documentarian 生成 API 文档。如果您想修改文档的 CSS 文件，或者想了解更多功能，请参阅 Documentarian 指南。

许可证

Laravel API 文档生成器是免费软件，受 MIT 许可证许可。

nickkuijpers / laravel-apidoc-generator

维护者

详细信息