d-scribe/laravel-apidoc-generator

此包已被弃用且不再维护。作者建议使用 knuckleswtf/scribe 包。

从您的 Laravel 应用程序生成美观的 API 文档

维护者

详情

github.com/ezra-obiwale/laravel-apidoc-generator

主页

源代码

安装: 431

依赖: 0

建议者: 0

安全: 0

星标: 0

关注者: 1

分支: 621

2.0.1 2020-04-02 01:14 UTC

Requires

Requires (Dev)

Suggests

MIT 9b57d5453b85a0c3950e0c38a2c0332a11bbd29a

  • Marcel Pociot <m.pociot.woop@gmail.com>

documentationapilaravel

This package is auto-updated.

Last update: 2023-05-24 23:37:32 UTC

README

此包已被弃用且不再维护。请使用 knuckleswtf/scribe 包。

Laravel API 文档生成器

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

php artisan apidoc:generate

Latest Stable VersionTotal Downloads License codecov.io Scrutinizer Code Quality Build Status StyleCI

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

安装

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

composer require d-scribe/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/d-scribe/laravel-apidoc-generator/config/apidoc.php 中的配置文件复制到您的项目中作为 config/apidoc.php。然后将其添加到 bootstrap/app.php
$app->configure('apidoc');

使用方法

在您能够生成文档之前，您需要配置 config/apidoc.php 中的几项内容。

  • url 这是要在请求示例中显示的 URL。它也用于 Postman 收集中。您可以在 .env 文件中使用 DOCUMENTATION_URL 设置它，否则默认为 APP_URL。

  • output 这是生成文档要写入的文件路径。默认：public/docs

  • postman 此包可以自动为您 routes 生成 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()
  {

  }
}

结果

Doc block result

指定请求参数

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

  • @urlParam 和 @bodyParam 注解接受参数的名称、其类型、可选的“required”标签，然后是描述。
  • @queryParam 注解接受参数的名称、可选的“required”标签，然后是描述
/**
 * @urlParam id int required The id of the post.
 */
public function showPost($id)
{
    // ...
}

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

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

结果

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

    /**
     * @urlParam id required The id of the post. Example: 2
     * @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）定义用于路由结果的转换器。该包将尝试使用以下步骤生成要转换的模型实例，并在第一个成功的地方停止：

  1. 检查是否有 @transformerModel 标签来定义正在转换的模型。如果没有，则使用转换器 transform() 方法的第一个参数的类。
  2. 从 Eloquent 模型工厂获取模型实例。
  3. 如果参数是 Eloquent 模型，则从数据库中加载第一个。
  4. 使用 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

对于大型响应体，您可能想使用实际响应的转储。您可以将此响应放入文件（作为 JSON 字符串）中，并在您的 Laravel 存储目录中引用它。例如，我们可以将此响应放入 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 键）。

类继承和方法重写

在超类包含所有路由方法且子类需要自定义文档的情况下，可以覆盖每个方法并在注释中提供文档。

/**
 * Books List
 *
 * Fetch a listing of books
 *
 * @responseFile path/to/index/response/file
 */
public function index()
{
    return parent::index();
}

或

可以在类注释中添加方法文档

/**
 * Book Resource
 *
 * The long description of the book resource
 *
 * @group Books
 *
 * @indexTitle Books List
 * @indexDescription Fetch a listing of books
 * @indexResponseFile path/to/index/response/file
 *
 * @storeTitle Create Book
 * @storeDescription Create a new book
 * @storeBodyParam title string required The title of the book
 * @storeResponseFile path/to/store/response/file
 *
 * ...
 */
class BookController extends CoolSuperController
{

}

注意事项

  • 多行不可用

基于标签生成

有时，您可能只想记录一组端点，例如，如果某些端点仅用于内部使用。引入 tags

路由组标签

可以将路由分组并添加标签

Route::group(['tags' => ['internal']], function () {
    Route::resource('/books', 'BooksController')
});

注解标签

虽然 @hideFromAPIDocumentation 隐藏了所有带标签的方法，但 @tags 允许更精确地记录方法。

/**
 * @tags internal
 */
public function index()
{
    # code...
}

与命令一起使用标签

使用上述任一种或两种标签方法，您可以使用 --skip-tags 选项跳过 内部 端点

php artisan apidoc:generate --skip-tags=internal

如果您只想生成 内部 端点，请使用 --only-tags 选项

php artisan apidoc:generate --only-tags=internal

注意： 路由组和方法的标签可能多个，例如 @tags internal important 注意： --skip-tags 和 --only-tags 可能针对多个标签，例如 `php artisan apidoc:generate --skip-tags=internal,important`

Postman 收集

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

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

修改生成的文档

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

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

php artisan apidoc:rebuild

您可以可选地使用 --output=path/to/output 覆盖输出目录。在重新构建的情况下，文档必须已存在于该位置。

如果您想重新生成文档，可以运行 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 许可证授权。