README

从现有的 Laravel 路由自动生成您的 API 文档。查看示例文档。

php artisan api:gen --routePrefix="settings/api/*"

许可证

此包是修改版，但所有权利归原作者所有。原始包可以在以下位置找到

安装

使用以下命令通过 composer 安装此包

$ composer require gilsonsouza/laravel-apidoc-generator

进入您的 config/app.php 文件并添加服务提供者

Mpociot\ApiDoc\ApiDocGeneratorServiceProvider::class,

用法

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

$ php artisan api:generate --routePrefix="api/v1/*"

此命令将扫描您的应用程序路由以查找匹配 api/v1/* 的 URI，并将解析这些控制器方法和表单请求。例如

// API Group Routes
Route::group(array('prefix' => 'api/v1', 'middleware' => []), function () {
	// Custom route added to standard Resource
	Route::get('example/foo', 'ExampleController@foo');
	// Standard Resource route
	Route::resource('example', 'ExampleController'));
});

可用的命令选项

选项	描述
`output`	用于生成文档的输出路径。默认：`public/docs`
`routePrefix`	用于生成的路由前缀 - 可以使用 `*` 作为通配符
`routes`	用于生成的路由名称 - 如果未提供 routePrefix，则必填
`middleware`	用于生成的中间件
`noResponseCalls`	禁用 API 响应调用
`noPostmanCollection`	禁用 Postman 收集创建
`useMiddlewares`	使用所有配置的路由中间件（对于 Laravel 5.3 的 `SubstituteBindings` 中间件是必需的）
`actAsUserId`	用于认证 API 响应调用的用户 ID
`router`	处理路由文件时要使用的路由器（可以是 Laravel 或 Dingo - 默认为 Laravel）
`bindings`	应在尝试检索路由结果时替换的路线绑定列表。语法格式：`binding_one,id`
`force`	强制重新生成现有/修改过的 API 路由
`header`	添加到示例请求的自定义 HTTP 标头。用冒号分隔头名称和值。例如：`--header 'Authorization: CustomToken'`

发布规则描述以进行自定义或翻译。

默认情况下，此包以英语返回描述。您可以发布包的语言文件，以自定义和翻译文档输出。

$ php artisan vendor:publish

发布文件后，您可以通过重命名 en 文件夹并编辑 public/vendor/apidoc/resources/lang 中的文件，以在您想要的任何语言中自定义或翻译描述。

它如何工作？

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

控制器文档块

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

在控制器之前使用 @resource 在文档块中很有用，因为它在API文档中为该控制器中定义的所有方法创建了一个分组（而不是为所有控制器列出所有方法），但使用 @resource 不是必需的。在 @resource 之后的简短描述应该是唯一的，以便锚点标签可以导航到此部分。可以在下方包含更长的描述。

您希望在API文档中包含的每个方法上，都应该有一个文档块。这应该包括作为第一条条目的唯一简短描述。可以添加可选的第二条条目以包含更多信息。两个描述将按以下所示的不同格式出现在API文档中。

/**
 * @resource Example
 *
 * Longer description
 */
class ExampleController extends Controller {

	/**
	 * This is the short description [and should be unique as anchor tags link to this in navigation menu]
	 *
	 * This can be an optional longer description of your API call, used within the documentation.
	 *
	 * @showInAPIDocumentation *Add this route to documentarian*
	 */
	 public function foo(){

	 }

结果

表单请求验证规则

为了显示有效的参数列表，您的API方法接受此包使用Laravel的表单请求验证。

public function rules()
{
    return [
        'title' => 'required|max:255',
        'body' => 'required',
        'type' => 'in:foo,bar',
        'thumbnail' => 'required_if:type,foo|image',
    ];
}

结果：

API响应

如果您的API路由接受 GET 方法，此包会尝试在禁用所有中间件的情况下调用API路由以获取示例API响应。

如果您的API需要一个认证用户，您可以使用 actAsUserId 选项指定将用于这些API调用的人员ID。

$ php artisan api:generate --routePrefix="api/*" --actAsUserId=1

如果您不想自动执行API响应调用，请使用 noResponseCalls 选项。

$ php artisan api:generate --routePrefix="api/*" --noResponseCalls

注意：示例API响应与预填充数据一起使用效果最佳。

Postman集合

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

如果您不想创建Postman集合，在生成API文档时使用 --noPostmanCollection 选项。

截至Laravel 5.3，添加到Postman集合中的默认基本URL将是您的Laravel config/app.php 文件中找到的URL。这很可能是 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文件后，使用 api:update 命令重新构建您的文档为静态HTML文件。

$ php artisan api:update

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

进一步修改

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

许可证

Laravel API文档生成器是免费软件，根据MIT许可证授权。

gilsonsouza / laravel-apidoc-generator

维护者

详细信息