README

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

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

安装

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

$ composer require mpociot/laravel-apidoc-generator

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

Mpociot\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',
    ];
}

结果：

控制器方法文档块

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

@transformer

使用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

@transformermodel标签在PHP 5.*中用于获取模型。在PHP 7中，指定用于transformer的模型是可选的。

@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文件中找到的。这很可能是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许可证的许可。

ninjacn / laravel-apidoc-generator

维护者

详细信息