超强API文档生成：Hyperf Swagger实战指南

2026-02-04 05:22:10作者：齐冠琰

还在为API文档编写而头疼？手动维护文档与代码不同步？Hyperf Swagger组件一键解决所有文档难题！

读完本文你将获得：

🚀 3分钟快速集成Swagger文档
📝 注解式API文档自动生成
🔧 多Server环境文档配置
🛡️ 验证器与文档无缝整合
🎨 自定义Swagger界面能力

快速安装与配置

Hyperf Swagger基于强大的zircote/swagger-php封装，只需简单几步即可集成：

composer require hyperf/swagger
php bin/hyperf.php vendor:publish hyperf/swagger

配置文件位于config/autoload/swagger.php，支持以下核心配置：

参数	说明	示例值
enable	启用文档生成	true
port	文档服务端口	9500
json_dir	JSON文件保存目录	BASE_PATH . '/storage/swagger'
auto_generate	自动生成文档	true

Swagger配置示例

注解式文档编写

Hyperf Swagger提供丰富的注解支持，让文档编写就像写注释一样简单：

use Hyperf\Swagger\Annotation as SA;

#[SA\Post(path: '/user/create', summary: '创建用户', tags: ['用户管理'])]
#[SA\RequestBody(
    description: '用户信息',
    content: [
        new SA\MediaType(
            mediaType: 'application/json',
            schema: new SA\Schema(
                required: ['username', 'email'],
                properties: [
                    new SA\Property(property: 'username', type: 'string'),
                    new SA\Property(property: 'email', type: 'string'),
                ]
            ),
        ),
    ],
)]
#[SA\Response(response: 200, description: '用户创建成功')]
public function createUser()
{
    // 业务逻辑
}

多Server环境支持

Hyperf支持多个Server同时运行，Swagger可以为每个Server生成独立的文档：

#[SA\HyperfServer('http')]
class UserController extends Controller
{
    #[SA\Get('/users', summary: '获取用户列表')]
    public function list()
    {
        // 仅对http server生效
    }
}

配置文件支持为每个Server设置独立的API信息：Server配置示例

验证器集成

Swagger可以与Hyperf验证器完美整合，实现文档与验证规则同步：

#[SA\Post('/user/save', summary: '保存用户信息')]
#[SA\QueryParameter(name: 'token', type: 'string', rules: 'required|string')]
#[SA\RequestBody(content: new SA\JsonContent(properties: [
    new SA\Property(property: 'nickname', type: 'string', rules: 'required|string'),
    new SA\Property(property: 'gender', type: 'integer', rules: 'required|integer|in:0,1,2'),
]))]
public function saveUser(SwaggerRequest $request)
{
    // 自动验证参数
}