Download the PHP package tangwei/apidocs without Composer

PHP Hyperf API Docs

English | 中文

基于 Hyperf 框架的 Swagger/OpenAPI 文档自动生成组件，支持 Swoole/Swow 引擎，为您提供优雅的 API 文档解决方案。

✨ 特性

• 🚀 自动生成 - 基于 PHP 8 Attributes 自动生成 OpenAPI 3.0/3.1 文档
• 🎯 类型安全 - 支持 DTO 模式，参数自动映射到 PHP 类
• 📝 多种 UI - 支持 Swagger UI、Knife4j、Redoc、RapiDoc、Scalar 等多种文档界面
• ✅ 数据验证 - 集成 Hyperf 验证器，支持丰富的验证注解
• 🔒 安全认证 - 支持 API Token 和多种安全方案
• 🔄 类型支持 - 支持数组、递归、嵌套、枚举等复杂类型
• 🎨 灵活配置 - 可自定义全局响应格式、路由前缀等
• 📦 开箱即用 - 零配置即可使用，同时支持深度定制

📋 环境要求

• PHP >= 8.1
• Hyperf >= 3.0
• Swoole >= 5.0 或 Swow

💡 使用须知

• 控制器方法尽可能返回具体的类（包含简单类型），这样能更好地生成文档
• 当返回类无法满足需求时，可使用 #[ApiResponse] 注解补充

📦 安装

默认使用 Swagger UI，推荐安装 Knife4j UI（可选）：

🚀 快速开始

1. 发布配置文件

配置文件将发布到 config/autoload/api_docs.php

2. 基础配置

完整配置文件示例：config/autoload/api_docs.php

3. 启动服务

• 启动成功后，访问 http://your-host:9501/swagger 即可查看 API 文档。
• 访问 http://your-host:9501/swagger/llms.txt 包含控制器每个Markdown页面的链接,可以用于Ai快速访问编程文档。
• 其他服务访问 http://your-host:9501/swagger/{service-name}.md 访问 {service-name} 服务的 Markdown 文档。

📖 使用指南

基础示例

1. 定义 DTO 类

2. 编写控制器

🎨 注解参考

控制器注解

#[Api] - 控制器标签

#[ApiOperation] - API 操作

#[ApiResponse] - 响应定义

泛型支持示例：

PHP 暂不支持泛型，可通过 #[ApiVariable] 实现：

控制器使用：

参数注解

#[RequestBody] - Body 参数

获取 POST/PUT/PATCH 请求的 JSON body 参数：

#[RequestQuery] - Query 参数

获取 URL 查询参数（GET 参数）：

#[RequestFormData] - 表单参数

获取表单数据（multipart/form-data）：

#[RequestHeader] - 请求头参数

获取请求头信息：

⚠️ 注意：一个方法不能同时注入 RequestBody 和 RequestFormData

属性注解

#[ApiModelProperty] - 属性描述

#[ApiHeader] - 请求头定义

#[ApiSecurity] - 安全认证

优先级：方法 > 类 > 全局

✅ 数据验证

内置验证注解

组件提供丰富的验证注解支持：

💡 提示：只需在控制器方法参数中添加 #[Valid] 注解即可启用验证

自定义验证

使用 Validation 注解

自定义验证注解

使用自定义验证：

🔧 高级特性

数组类型支持

方法一：使用 PHPDoc

方法二：使用 ArrayType 注解

嵌套对象

枚举支持

全局响应格式

配置全局响应包装类：

定义全局响应类：

文件上传

🎭 多种 UI 界面

访问不同的 UI 界面：

• Swagger UI: http://your-host:9501/swagger
• Knife4j: http://your-host:9501/swagger/knife4j
• Redoc: http://your-host:9501/swagger/redoc
• RapiDoc: http://your-host:9501/swagger/rapidoc
• Scalar: http://your-host:9501/swagger/scalar

⚙️ 配置参考

DTO 数据映射

api-docs 依赖 DTO 组件，更多详情请查看 DTO 文档

#[Dto] 注解

标记为 DTO 类：

• 可以设置返回格式 #[Dto(Convert::SNAKE)]，批量转换为下划线格式的 key
• Dto 注解不会生成文档，要生成对应文档使用 JSONField 注解

#[JSONField] 注解

用于设置属性的别名：

• 设置 JSONField 后会生成代理类，生成 alias_name 属性
• 接收和返回字段都以 alias_name 为准

RPC 支持

返回 PHP 对象

aspects.php 中配置：

当框架导入 symfony/serializer (^5.0) 和 symfony/property-access (^5.0) 后，在 dependencies.php 中配置映射关系：

💡 最佳实践

1. DTO 类设计

• 使用有意义的类名，如 CreateUserRequest、UserResponse
• 为每个属性添加 ApiModelProperty 注解
• 分离 Request 和 Response 定义
• 合理使用验证注解

2. 控制器设计

• 使用 Api 注解对控制器分组
• 为每个方法添加 ApiOperation 描述
• 尽可能返回具体类型而非 array
• 合理使用 ApiResponse 定义响应格式

3. 安全性

• 生产环境禁用文档服务
• 使用 ApiSecurity 控制 API 认证
• 使用 hidden: true 隐藏敏感接口

4. 性能优化

• 开发环境使用文档，生产环境禁用
• 合理使用缓存
• 避免过深的嵌套结构

📚 常见问题

Q: 文档没有生成？

A: 检查以下几点：

1. 配置文件中 enable 是否为 true
2. 查看日志是否有错误信息

Q: 如何定义数组类型？

A: 使用 PHPDoc 注释或 ArrayType 注解：

Q: 如何隐藏某些接口？

A: 使用 hidden 参数：

Q: 如何自定义响应格式？

A: 使用 ApiResponse 注解或配置全局响应类：

Q: 支持哪些验证规则？

A: 支持所有 Hyperf Validation 规则。详见 Hyperf 验证器文档。

Q: AutoController 注解支持吗？

A: 支持，但只会收集 POST 方法。建议使用标准路由注解以获得更好的文档生成效果。

📖 示例项目

完整示例请参考 example 目录

🔗 相关链接

• Hyperf 官方文档
• OpenAPI 规范
• Swagger UI
• Knife4j
• 示例项目

如果这个项目对你有帮助，请给个 ⭐ Star！