README

自动从您现有的Laravel路由生成API文档。请参阅示例文档。

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

安装

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

composer require oxycoder/laravel-apidoc-generator

使用Laravel < 5.5？请转到您的 config/app.php 并添加服务提供者

Oxycoder\ApiDoc\ApiDocGeneratorServiceProvider::class,

使用Laravel < 5.4？使用版本1.0！对于Laravel 5.4及以上版本，请使用2.0。

用法

要生成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');
});

可用命令选项

定制或翻译。

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

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.
	 *
	 */
	 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',
    ];
}

您也可以在函数内部使用validate

$validatedData = $request->validate([
    'title' => 'required|max:255',
    'body' => 'required',
    'type' => 'in:foo,bar',
    'thumbnail' => 'required_if:type,foo|image',
]);

结果：

控制器方法文档块

您可以覆盖响应的结果。这也会显示除GET之外的其他请求方法的响应。

@transformer

使用转换器，您可以定义用于方法结果的转换器。如果可以找到转换器，它将尝试下一部分以获取结果。将使用第一个成功的结果。

检查是否存在 transformermodel 标签来定义模型
从 modelfactory 获取模型
如果参数是 Eloquent 模型，它将加载数据库中的第一个。
类的全新实例

/**
 * @transformer \Mpociot\ApiDoc\Tests\Fixtures\TestTransformer
 */
public function transformerTag()
{
    return '';
}

@transformercollection

这与 @transformer 标签的思路相同，但有一个不同之处，而不是返回一个项目，它将生成包含两个项目的集合的返回值

/**
 * @transformercollection \Mpociot\ApiDoc\Tests\Fixtures\TestTransformer
 */
public function transformerCollectionTag()
{
    return '';
}

@transformermodel

@transformermodel 标签对于 PHP 5.* 获取模型是必需的。对于 PHP 7，指定用于转换器的模型是可选的。

@response

如果您想显式指定函数的结果，可以在文档块中设置它。

/**
 * @response {
 *  data: [],
 *}
 */
public function responseTag()
{
    return '';
}

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 App 中以进行更简单的 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 来告诉更新命令文档的位置。

跳过单个路由

如果您想从匹配给定前缀的路由列表中跳过一个单个路由，您可以在不希望记录文档的控制器方法上使用 @hideFromAPIDocumentation 标签。

许可证

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

oxycoder / laravel-apidoc-generator

维护者

详细信息