README

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

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

安装

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

$ composer require mpociot/laravel-apidoc-generator

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

Mpociot\ApiDoc\ApiDocGeneratorServiceProvider::class,

用法

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

$ php artisan api:generate --routePrefix="api/v1/*"

此命令将扫描您应用程序的路由，以匹配api/v1/*的URI，并将解析这些控制器方法和表单请求。

可用的命令选项

选项	描述
`output`	生成文档使用的输出路径。默认：`public/docs`
`routePrefix`	用于生成的路由前缀 - 可以使用`*`作为通配符
`routes`	用于生成的路由名称 - 如果没有提供routePrefix，则为必需
`middleware`	用于生成的中间件
`noResponseCalls`	禁用API响应调用
`noPostmanCollection`	禁用Postman集合创建
`actAsUserId`	用于认证API响应调用的用户ID
`router`	处理路由文件时要使用的路由器（可以是Laravel或Dingo - 默认为Laravel）
`bindings`	应替换以检索路由结果的路由绑定列表。语法格式：`binding_one,id`
`force`	强制重新生成现有/已修改的API路由
`header`	添加到示例请求的自定义HTTP头。用":"分隔头部名称和值。例如：`--header 'Authorization: CustomToken'`

发布规则描述以进行自定义或翻译。

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

$ php artisan vendor:publish

文件发布后，您可以通过重命名en文件夹并编辑public/vendor/apidoc/resources/lang中的文件来在您想要的任何语言中自定义或翻译描述。

它如何工作？

此包使用以下资源生成API文档

控制器文档块

此包使用HTTP控制器文档块来创建目录表并显示API方法的描述。

/**
 * This is the short description
 *
 * 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',
    ];
}

结果：

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选项。

修改生成的文档

如果你想修改生成的文档内容，请编辑生成的index.md文件。该文件的默认位置是：public/docs/source/index.md。

编辑markdown文件后，使用api:update命令重新构建你的文档为静态HTML文件。

$ php artisan api:update

作为可选参数，你可以使用--location来告诉更新命令文档的位置。

跳过单个路由

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

进一步修改

该包使用Documentarian来生成API文档。如果你想修改文档的CSS文件，或者想了解更多信息，请查看Documentarian指南。

许可

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

georgechaduneli / laravel-apidoc-generator

维护者

详细信息