# dcat 注释自动生成接口文档

**Repository Path**: dcat_admin/apidocs

## Basic Information

- **Project Name**: dcat 注释自动生成接口文档
- **Description**: dcat 注释自动生成接口文档
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-27
- **Last Updated**: 2026-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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. 发布配置

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

2. 生成 JSON 文件

```bash
php artisan apidocs:generate
```

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` 关闭结果面板。

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

```php
'ui' => [
    'search' => false,
],
```

### 常用 UI 配置

```php
'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`。

如需关闭：

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

### 环境切换 servers

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

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

也可以使用 OpenAPI 原生写法：

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

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

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

### 分组/标签优化

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

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

```php
use DcatPlus\Apidocs\Attributes\Group;

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

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

### 隐藏内部接口

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

```php
use DcatPlus\Apidocs\Attributes\Group;

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

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

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

## 注释示例

```php
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` 为空时作为兜底。