README

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

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

安装

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

$ composer require famdirksen/laravel-apidoc-generator

转到您的config/app.php并添加服务提供者

Mpociot\ApiDoc\ApiDocGeneratorServiceProvider::class,

Laravel版本小于5.4？使用1.0版！对于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是一个doc块很有用，因为它在API文档中为该控制器中定义的所有方法创建一个组（而不是在单个列表中列出所有控制器的方法），但使用@resource不是必需的。@resource后的简短描述应该是唯一的，以便允许锚点标签导航到此部分。可以包括一个更长的描述。

在每个您希望包含在API文档中的控制器方法上方，应该有一个doc块。它应该包括一个唯一的简短描述作为第一个条目。可以添加一个可选的第二条目，包含更多信息。两种描述将以不同的格式显示在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',
    ];
}

结果：

控制器方法文档块

可以覆盖响应的结果。这将还会显示GET以外的其他请求方法的响应。

@transformer

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

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

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

@transformercollection

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

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

@transformermodel

在PHP 5.*版本中，需要使用@transformermodel标签来获取模型。对于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应用中，以进行更简单的API测试和使用。

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

从Laravel 5.3开始，添加到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文件后，使用api:update命令以重建您的文档为静态HTML文件。

$ php artisan api:update

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

跳过单个路由

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

进一步修改

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

许可证

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

famdirksen / laravel-apidoc-generator

维护者

详细信息