README

在您的 Lumen 应用程序中使用 Dingo 路由器自动生成 API 文档。查看示例文档。

php artisan api:generate --router="dingo" --routePrefix="v1"

安装

使用以下命令使用 composer 需求此包

$ composer require davmixcool/lumen-apidoc-generator

前往您的 bootstrap/app.php 并注册服务提供者

$app->register(Davmixcool\ApiDoc\ApiDocGeneratorServiceProvider::class);

使用

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

$ php artisan api:generate --router="dingo" --routePrefix="v1"

此命令将扫描您应用程序的路由，查找匹配 v1/* 的 URI，并将解析这些控制器方法和验证规则。例如

$api = app('Dingo\Api\Routing\Router');

$api->version('v1', function ($api) {
    $api->group(['namespace' => 'App\Http\Controllers'], function ($api) {
        // Custom get route added to standard Resource
        $api->get('example/get', 'ExampleController@foo');
        //Custom post route added to standard Resource
        $api->post('example/post', 'ExampleController@save');
    });
});

可用命令选项

自定义或翻译。

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

$ 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 方法接受的，此包使用 Lumen 验证辅助方法验证。

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

结果：

控制器方法文档块

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

@transformer

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

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

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

@transformercollection

这个想法与@tranformer标签相同，只有一个不同之处，它不会返回一个项目，而是会返回一个包含两个项目的集合

/**
 * @transformercollection \Davmixcool\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 --router="dingo" --routePrefix="v1" --actAsUserId=1

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

$ php artisan api:generate --router="dingo" --routePrefix="v1" --noResponseCalls

注意：示例API响应与已播种数据配合使用效果最佳。

Postman集合

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

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

'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告诉更新命令您的文档在哪里可以找到。

跳过单个路由

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

许可证

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

davmixcool / lumen-apidoc-generator

维护者

详情