Download the PHP package dcat-plus/apidocs without Composer

dcat-plus/apidocs

基于 Laravel 8 的轻量 API 文档生成包（兼容 PHP 7.4）。

当前版本重点：基于控制器注释提取文档，输出 OpenAPI 3.0.3 JSON。

支持的注释标签

• @authenticated / @unauthenticated
• @deprecated
• @queryParam page int required 页码 example:1
• @urlParam id int required 主键ID
• @header Authorization string required Bearer Token
• @bodyParam year int required 年份 example:2025
• @response 200 {"code":0,"message":"ok"}

DcatPlus Attributes

支持从以下 PHP Attributes 提取文档信息（无需额外迁移注释）：

• #[\DcatPlus\Apidocs\Attributes\Group(...)]（类/方法分组，方法优先）
• #[\DcatPlus\Apidocs\Attributes\QueryParameter(...)]
• #[\DcatPlus\Apidocs\Attributes\BodyParameter(...)]
• #[\DcatPlus\Apidocs\Attributes\PathParameter(...)]
• #[\DcatPlus\Apidocs\Attributes\HeaderParameter(...)]

说明：同名参数下，显式注释（DocBlock）优先，Attributes 次之，validate 推断最后兜底。

注意：Attributes 解析依赖 PHP 8+ 的反射能力；在 PHP 7.4 运行时会自动忽略 Attributes，仅保留注释与 validate 推断。

认证推断规则：

• 默认自动标记为 Bearer 认证，并补 401 Unauthorized 响应（可通过 auth.default_authenticated 配置关闭）。
• 路由包含 auth/auth:* 中间件时，也会自动标记为 Bearer 认证。
• @authenticated：强制标记为需要认证。
• @unauthenticated：强制标记为不需要认证（security: []），用于覆盖中间件推断。

用法

1. 发布配置

2. 生成 JSON 文件

3. 在线查看

• UI: /docs/apidocs
• JSON: /docs/apidocs.json

Stoplight UI 功能

文档页使用 Stoplight Elements 渲染 OpenAPI，并额外内置了接口搜索。

接口搜索

默认开启。打开 /docs/apidocs 后，右上角会出现搜索框，可按以下内容搜索：

• 请求方法：GET、POST、PUT、DELETE 等
• 接口路径：如 /students/{id}
• 接口标题：DocBlock 第一行摘要
• 接口分组：Group Attribute 分组
• operationId

搜索结果支持点击跳转到对应接口，也可以输入关键词后按 Enter 打开第一个结果，按 Esc 关闭结果面板。

如需关闭搜索，可在配置中设置：

常用 UI 配置

说明：

• hide_try_it：隐藏 Stoplight 的在线调试功能。
• hide_schemas：隐藏左侧 Schemas 目录。
• layout：控制 Stoplight Elements 布局，responsive 适合独立文档页。
• search：控制本扩展额外提供的接口搜索框。

导出 OpenAPI JSON

默认开启。文档页右上角会显示“导出 JSON”按钮，打开当前文档的 OpenAPI JSON 地址，默认是 /docs/apidocs.json。

如需关闭：

环境切换 servers

OpenAPI 的 servers 会被 Stoplight 用于在线调试环境。配置多个环境后，文档页右上角会显示环境下拉框，切换后会把选中的 server 放到 OpenAPI servers 列表首位，让 Try It 默认使用该环境。

也可以使用 OpenAPI 原生写法：

如需关闭右上角环境切换：

分组/标签优化

推荐使用 DcatPlus\Apidocs\Attributes\Group 标记控制器或方法分组。分组会转换成 OpenAPI tags，Stoplight 左侧目录会按 tags 组织接口。

Group 的第三个参数是排序值，数字越小越靠前。方法上的 Group 优先级高于类上的 Group。

生成器会把分组说明写入 OpenAPI tags.description，并按 weight 和路径整理 OpenAPI tags、paths，让左侧目录更稳定。未设置排序值的分组会排在后面，并按名称排序。

隐藏内部接口

给控制器方法 DocBlock 添加 @internal 后，该接口默认不会出现在文档和 JSON 中。

如需临时生成内部接口文档，可开启：

注释示例

访问控制

• local 环境默认允许访问。
• 非 local 环境默认走 Gate::allows('viewApiDocs')。

扫描范围

优先使用核心配置：

• api_path：按路由前缀筛选（默认 api）
• api_domain：按域名筛选（可选）

兼容配置：

• scan.prefixes 仍可用，仅在 api_path 为空时作为兜底。