README

Laravel API 文档生成器

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

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

image image codecov.io Scrutinizer 代码质量构建状态 StyleCI 依赖状态 安装

使用以下命令通过 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 集合创建 useMiddlewares 使用所有配置的路由中间件（对于 Laravel 5.3 的 SubstituteBindings 中间件是必需的） 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 方法的描述。

/**

• 这是简短描述
• 这可以是 API 调用的可选较长的描述，用于文档中。

*/ 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

Note: The example API responses work best with seeded data.

Postman 集合

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

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

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

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

$ php artisan api:update

作为可选参数，您可以使用 --location 来指定文档的位置。跳过单个路由

如果您想跳过与给定前缀匹配的路由列表中的单个路由，您可以在不需要文档的控制器方法上使用 @hideFromAPIDocumentation 标签。进一步修改

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

Laravel API文档生成器是免费软件，根据MIT许可证授权。