README

基于 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: []），用于覆盖中间件推断。

用法

发布配置

php artisan vendor:publish --tag=apidocs-config

生成 JSON 文件

php artisan apidocs:generate

在线查看

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' => [
    'search' => false,
],

常用 UI 配置

'ui' => [
    'title' => 'API Docs',
    'theme' => 'light', // light、dark、system
    'hide_try_it' => false,
    'hide_schemas' => false,
    'logo' => '',
    'try_it_credentials_policy' => 'include', // omit、include、same-origin
    'layout' => 'responsive', // sidebar、responsive、stacked
    'search' => true,
],

说明：

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

导出 OpenAPI JSON

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

如需关闭：

'ui' => [
    'export_json' => false,
],

环境切换 servers

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

'servers' => [
    'Local' => 'api',
    'Test' => 'https://test.example.com/api',
    'Prod' => 'https://api.example.com/api',
],

也可以使用 OpenAPI 原生写法：

'servers' => [
    [
        'url' => 'https://api.example.com/api',
        'description' => 'Prod',
    ],
],

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

'ui' => [
    'server_switcher' => false,
],

分组/标签优化

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

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

use DcatPlus\Apidocs\Attributes\Group;

#[Group('Clife运动', 'Clife运动记录与统计接口', 15)]
class SportController extends BaseClifeController
{
    // ...
}

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

隐藏内部接口

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

use DcatPlus\Apidocs\Attributes\Group;

/**
 * 内部同步接口
 *
 * @internal
 */
#[Group('内部', '内部维护接口', 999)]
public function sync()
{
    // ...
}

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

'scan' => [
    'include_internal' => true,
],

注释示例

use DcatPlus\Apidocs\Attributes\Group;

/**
 * 查询学生体测统计
 * 返回区域体测汇总数据。
 *
 * @authenticated
 * @queryParam page int optional 页码 example:1
 * @queryParam page_size int optional 每页条数 example:20
 * @urlParam region_id int required 区域ID
 * @bodyParam year int required 年份 example:2025
 * @response 200 {"code":0,"message":"ok","data":[]}
 */
#[Group('体测-区域', '区域维度的体测统计接口', 20)]
public function index(Request $request, $region_id)
{
    // ...
}

访问控制

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

扫描范围

优先使用核心配置：

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

兼容配置：

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

dcat-plus/apidocs

包简介

README 文档