README

一个为 Webman 框架设计的自动 API 文档生成器，界面参考 Apifox 和 Hoppscotch。

特性

✅ 基于 PHP 注解自动生成 API 文档
✅ 支持多种 HTTP 方法（GET, POST, PUT, DELETE, PATCH）
✅ 请求/响应参数自动解析
✅ 美观的 Apifox/Hoppscotch 风格 UI
✅ 在线 API 测试功能
✅ 支持认证配置
✅ 导出 OpenAPI/Swagger 格式
✅ Webman 插件规范，一键安装
✅ 支持 Webman 1.x 和 2.x

安装

composer require dasher/webman-docs

安装后会自动完成以下操作：

复制配置文件到 config/plugin/dasher/webman-docs/
注册路由
复制公共资源文件

无需任何手动配置，开箱即用！

快速开始

1. 在控制器中添加注解

<?php

namespace app\controller;

use support\Request;
use Dasher\WebmanDocs\Annotation as Api;

#[Api\Group(name: '用户管理', description: '用户相关接口')]
class UserController
{
    #[Api\Endpoint(
        path: '/api/users',
        method: 'GET',
        summary: '获取用户列表',
        description: '分页获取所有用户信息'
    )]
    #[Api\QueryParam(name: 'page', type: 'integer', example: 1, description: '页码')]
    #[Api\QueryParam(name: 'limit', type: 'integer', example: 10, description: '每页数量')]
    #[Api\Response(status: 200, description: '成功', schema: [
        'code' => 200,
        'data' => [
            'list' => [['id' => 1, 'name' => '张三']],
            'total' => 100
        ]
    ])]
    public function index(Request $request)
    {
        return json(['code' => 200, 'data' => []]);
    }

    #[Api\Endpoint(
        path: '/api/users',
        method: 'POST',
        summary: '创建用户',
        description: '创建新用户'
    )]
    #[Api\BodyParam(name: 'name', type: 'string', required: true, example: '张三', description: '用户名')]
    #[Api\BodyParam(name: 'email', type: 'string', required: true, example: 'zhangsan@example.com', description: '邮箱')]
    #[Api\Response(status: 201, description: '创建成功')]
    public function store(Request $request)
    {
        return json(['code' => 201, 'message' => '创建成功']);
    }
}

2. 访问文档

浏览器访问：http://your-domain/api-docs

就这么简单！✨

注解说明

注解	说明	使用位置
`@Api\Group`	定义 API 分组	类
`@Api\Endpoint`	定义 API 端点	方法
`@Api\QueryParam`	URL 查询参数	方法
`@Api\BodyParam`	请求体参数	方法
`@Api\Header`	请求头参数	方法
`@Api\Response`	响应定义	方法
`@Api\Auth`	认证配置	类/方法

配置选项

配置文件位于 config/plugin/dasher/webman-docs/app.php：

<?php

return [
    'enable' => true,
    'title' => 'API Documentation',
    'description' => 'Auto-generated API documentation',
    'version' => '1.0.0',
    'controllers' => [
        base_path() . '/app/controller',
    ],
    'route' => [
        'prefix' => '/api-docs',
    ],
    'auth' => [
        'enabled' => false,
        'token' => '',
    ],
];

命令行工具

# 导出文档为 JSON
php vendor/bin/generate-docs.php --output docs.json

# 导出文档为 YAML
php vendor/bin/generate-docs.php --output docs.yaml --format yaml

# 查看帮助
php vendor/bin/generate-docs.php --help

示例代码

查看 examples/ 目录获取完整的控制器示例：

UserController.php - 用户管理完整示例
ProductController.php - 商品管理完整示例

截图预览

UI 界面采用现代化的设计风格：

📱 响应式布局，支持移动端
🔍 实时搜索功能
🧪 在线 API 测试
📤 一键导出 OpenAPI
🎨 清爽的视觉设计

环境要求

PHP >= 8.0
Webman >= 1.0 或 >= 2.0
Composer

常见问题

Q: 安装后访问 /api-docs 404？

A: 确保 Webman 已重启，检查路由是否正确加载。

Q: 注解不生效？

A: 确认使用了正确的命名空间 Dasher\WebmanDocs\Annotation，并检查 PHP 版本 >= 8.0。

Q: 支持 Webman 2.x 吗？

A: 是的，完全支持 Webman 1.x 和 2.x。

Q: 如何启用认证保护？

A: 修改配置文件中的 auth.enabled 为 true，并设置 token。

GitHub

https://github.com/syjbd/phpdoc

License

MIT

dasher / webman-docs

Maintainers

Package info

Statistics

Security