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

还在为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)
{
    // 自动验证参数
}

自定义界面与高级功能

如果默认的Swagger UI不满足需求，可以完全自定义界面：HTML模板配置

支持的功能包括：

• ✅ 自动生成和手动生成文档模式
• ✅ 实时文档预览
• ✅ OpenAPI 3.0规范支持
• ✅ 多语言支持
• ✅ Schema定义重用

生成与部署

启用auto_generate后，框架启动时自动生成文档。也可手动执行：

php bin/hyperf.php gen:swagger

生成的文档默认可通过 http://127.0.0.1:9500/swagger 访问。

总结

Hyperf Swagger将API文档从负担变为资产，通过注解驱动的方式确保文档与代码永远同步。无论是内部API管理还是对外接口提供，都是微服务开发的得力助手。

下一步行动：

1. 安装hyperf/swagger组件
2. 配置扫描路径和服务器信息
3. 为现有接口添加Swagger注解
4. 访问/swagger查看自动生成的文档

记得点赞、收藏、关注，下期分享Hyperf微服务治理实战！