README

从现有的 Laravel/Lumen/Dingo 路由自动生成您的 API 文档。以下是输出结果的样子。

php artisan apidoc:generate

注意：这是版本 3 的文档，与版本 2 有很大不同。如果您使用的是 v2，可以在此处查看其文档 here。但我们强烈建议您升级，因为 v3 更稳定，并修复了 v2 中许多问题。

安装

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

$ composer require mpociot/laravel-apidoc-generator

Laravel

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

php artisan vendor:publish --provider="Mpociot\ApiDoc\ApiDocGeneratorServiceProvider" --tag=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 收集，请将此选项设置为 true。默认：true
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

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

注意：使用@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注释接受参数名称、其类型、可选的“必需”标签以及其描述。
@queryParam注释接受参数名称、可选的“必需”标签以及其描述

/**
 * @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()
{
    // ...
}

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

以上

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

    /**
     * @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
     */

指示认证状态

您可以在方法上使用@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字符串）中，并链接到它。例如，我们可以将此响应放在storage/responses目录下的名为users.get.json的文件中

{"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许可证。

szwss / laravel-apidoc-generator

维护者

详情