README

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

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

安装

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

$ composer require mpociot/laravel-apidoc-generator

使用Laravel < 5.5？请前往您的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

在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 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标签。

进一步修改

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

许可证

Laravel API文档生成器是免费软件，许可协议为MIT。

ntopulos / laravel-apidoc-generator

维护者

详细信息