PHPackages                             busyphp/api-doc - 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. busyphp/api-doc

ActiveLibrary[API Development](/categories/api)

busyphp/api-doc
===============

用于BusyPHP接口文档实时预览模块

v2.0.2(4y ago)131CC-BY-NC-4.0HTML

Since Sep 28Pushed 2y ago1 watchersCompare

[ Source](https://github.com/busyphp/api-doc)[ Packagist](https://packagist.org/packages/busyphp/api-doc)[ RSS](/packages/busyphp-api-doc/feed)WikiDiscussions 3.0 Synced 1mo ago

READMEChangelog (9)Dependencies (3)Versions (11)Used By (0)

BusyPHP ApiDoc 说明
=================

[](#busyphp-apidoc-说明)

> 本辅助插件主要用于接口文档自动化生成

书写规范
----

[](#书写规范)

### 保留关键字

[](#保留关键字)

> `@`、`#`、`*`
> 书写中如果必须使用以上关键字，请转义输入，如：`\@`，`\#`，`\*`

### 控制器

[](#控制器)

控制器类必须书写注释，且必须写到 `class className {` 之上，书写格式为：

```
/**
 * 这里写接口分组名称
 * @desc 分组说明，说明这个分组的作用
 */
class TestController extends \BusyPHP\Controller {

}
```

### 方法

[](#方法)

API接口方法必须书写注释，且必须写到 `public function functionName() {` 之上

#### 参数说明

[](#参数说明)

> @api 声明接口请求方式，如get 或 post，如：`@api post`
> @param 申明请求参数，可以写多个，格式：`@param 参数类型 参数名称 参数说明 [二级参数..]`，参数前面加 "\*" 号代表这个参数是必填的。二级参数格式：`# 参数名称 : 参数说明`
> @return 声明返回类型和结构，格式：`返回类型 [返回结构...]`，目前支持 `Json`返回类型，如：`@return Json` 返回结构格式：`# 参数名称 参数类型 : 参数说明 [多级参数...]` 几个"#"号代表几级参数，只有`array`,`object`参数类型才会解析多级参数 @example 声明输出示例，可以直接复制测试接口返回的内容 @desc 接口说明

```
class TestController extends \BusyPHP\Controller {

    // 以下是书写格式

    /**
     * 这里写接口说明，如：获取用户资料
     * @api post
     * @param int *test 参数1说明
     * @param string test2 参数2说明  [
     *     # type_a: 用户ID
     *     # type_b: 用户姓名
     * ]
     * @param string test3 参数3....
     * @return Json [
     *      # list array: 消息集合  [
     *          ## id string: 消息ID
     *          ## title string: 消息标题
     *          ## read boolean: 是否已读
     *          ## operate object: 操作结构 [
     *              ### type int: 操作类型，`1 打开页面`，`2 打开内部浏览器`，`3 打开外部浏览器`
     *              ### value string: 操作内容
     *          ]
     *      ]
     * ]
     * @example {list:[], page: 1}
     * @desc 说明这个接口的功能等
     */
    public function test() {

    }
}
```

生成文档
----

[](#生成文档)

在对应要展示文档的控制中使用

```
class ShowController extends \BusyPHP\Controller {

    /**
     * 展示接口文档
     */
    public function doc() {

        $apiDoc = new \BusyPHP\apidoc\ApiDoc('要解析的类文件路径', '要解析的类名等');
        $apiDoc->getScan()->removeSuffix('移除控制器类名指定的后缀', '移除方法名指定的后缀');

        $apiDoc->getScan()->removeSuffix(function($name, $class) {
            // 闭包处理控制器类名称
            return '处理后的类名称';
        }, function($name, $class) {
            // 闭包处理方法名称
            return '处理后的方法名称';
        });

        $apiDoc->getInfo()->setTitle('文档标题');
        $apiDoc->getInfo()->setDebugRootUrl('测试模式入口地址');
        $apiDoc->getInfo()->setReleaseRootUrl('发布模式入口地址');
        $apiDoc->getInfo()->setDescription('文档说明');

        // 添加错误代码
        $apiDoc->getInfo()->addErrorCode('错误代码', '说明', '解决方法');

        // 全局请求头参数
        $apiDoc->getInfo()->addHeader('header_params', true, '请求头参数说明');

        // 添加全局返回结构
        $apiDoc->getInfo()->addReturn(new \BusyPHP\apidoc\structs\ReturnItem('参数', '类型', new \BusyPHP\apidoc\structs\DataStructure('参数说明')));

        // 添加全局参数
        $apiDoc->getInfo()->addParam(new \BusyPHP\apidoc\structs\ParamItem('param1', 'boolean', true, new \BusyPHP\apidoc\structs\DataStructure('参数说明')));

        // 添加附录
        $apiDoc->getInfo()->addAppendix(new \BusyPHP\apidoc\structs\AppendixItem('附录1', '附录1描述'));

        return $apiDoc->renderToHTML('XX项目接口文档');
    }
}
```

###  Health Score

27

—

LowBetter than 49% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity9

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity60

Established project with proven stability

 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

Every ~108 days

Recently: every ~176 days

Total

10

Last Release

1085d ago

Major Versions

v1.0.5 → v2.0.02021-11-12

v2.0.2 → 3.0.x-dev2023-05-28

### Community

Maintainers

![](https://www.gravatar.com/avatar/de6a1fa6381f7af7435f453177ce4f8ddc72a4dcd4c9b9ac3530c9d1180b7c60?d=identicon)[busylife](/maintainers/busylife)

---

Top Contributors

[![brisk-php](https://avatars.githubusercontent.com/u/16153680?v=4)](https://github.com/brisk-php "brisk-php (25 commits)")

### Embed Badge

![Health badge](/badges/busyphp-api-doc/health.svg)

```
[![Health](https://phpackages.com/badges/busyphp-api-doc/health.svg)](https://phpackages.com/packages/busyphp-api-doc)
```

###  Alternatives

[twilio/sdk

A PHP wrapper for Twilio's API

1.6k92.9M272](/packages/twilio-sdk)[aheinze/cockpit

Cockpit Headless CMS

5.4k2.0k4](/packages/aheinze-cockpit)[m165437/laravel-blueprint-docs

API Blueprint Renderer for Laravel

22779.0k](/packages/m165437-laravel-blueprint-docs)[ezsystems/ezplatform-graphql

GraphQL server for the eZ Platform Open Source CMS Repository.

31650.2k12](/packages/ezsystems-ezplatform-graphql)

PHPackages © 2026

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