README

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

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

安装

使用Composer安装此包。在文件composer.json中添加2个包

   "minhngoc/lumen-apidoc-generator": "dev-master"

运行命令更新包后

   $ composer update

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

$app->instance('path.config', app()->basePath() . DIRECTORY_SEPARATOR . 'config');
$app->instance('path.storage', app()->basePath() . DIRECTORY_SEPARATOR . 'storage');
$app->register(Dingo\Api\Provider\LumenServiceProvider::class);
$app->register(Minhngoc\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标签
从modelfactory获取模型
如果参数是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来告诉更新命令文档的位置。

跳过单个路由

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

许可证

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

minhngoc / lumen-apidoc-generator

维护者

详细信息