PHPackages                             dcat-plus/apidocs - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. dcat-plus/apidocs

ActiveLibrary[API Development](/categories/api)

dcat-plus/apidocs
=================

API docs generator for Laravel 8 based on controller annotations.

1.0.1(3mo ago)01↓50%MITPHPPHP ^7.4

Since Apr 27Pushed 1mo agoCompare

[ Source](https://github.com/ycookies/apidocs)[ Packagist](https://packagist.org/packages/dcat-plus/apidocs)[ RSS](/packages/dcat-plus-apidocs/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (4)Versions (2)Used By (0)

dcat-plus/apidocs
=================

[](#dcat-plusapidocs)

基于 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
-------------------

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

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

2. 生成 JSON 文件

```
php artisan apidocs:generate
```

3. 在线查看

- UI: `/docs/apidocs`
- JSON: `/docs/apidocs.json`

Stoplight UI 功能
---------------

[](#stoplight-ui-功能)

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

### 接口搜索

[](#接口搜索)

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

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

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

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

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

### 常用 UI 配置

[](#常用-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

[](#导出-openapi-json)

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

如需关闭：

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

### 环境切换 servers

[](#环境切换-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` 为空时作为兜底。

###  Health Score

33

—

LowBetter than 72% of packages

Maintenance87

Actively maintained with recent releases

Popularity1

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity34

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

92d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/20916476?v=4)[YeRic](/maintainers/ycookies)[@ycookies](https://github.com/ycookies)

---

Top Contributors

[![ycookies](https://avatars.githubusercontent.com/u/20916476?v=4)](https://github.com/ycookies "ycookies (3 commits)")

### Embed Badge

![Health badge](/badges/dcat-plus-apidocs/health.svg)

```
[![Health](https://phpackages.com/badges/dcat-plus-apidocs/health.svg)](https://phpackages.com/packages/dcat-plus-apidocs)
```

###  Alternatives

[laravel/ai

The official AI SDK for Laravel.

1.0k3.2M250](/packages/laravel-ai)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M134](/packages/roots-acorn)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

77922.3M186](/packages/laravel-mcp)[laravel/folio

Page based routing for Laravel.

603583.7k34](/packages/laravel-folio)[illuminate/queue

The Illuminate Queue package.

20432.6M1.7k](/packages/illuminate-queue)[laravel/surveyor

Static analysis tool for Laravel applications.

86121.4k14](/packages/laravel-surveyor)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)