hyperfai / swagger

2.0.4 2026-09-22 06:05 UTC

Requires

• php: >=8.2
• hyperf/command: ^3.0
• hyperf/config: ^3.0
• hyperf/di: ^3.0
• hyperf/framework: ^3.0

MIT

• joyqhs

• swagger
• hyperf
• hyperfai
• hyperfai-swagger

Published on Packagist.org on 2026-09-22 06:05 UTC

README

安装

composer require joyqhs/hyperf-swagger

根据注解生成 API 文档

# 类的注解  分组
use joyqhs\Swagger\Annotation\Api;
# 方法的注解 接口描述
use joyqhs\Swagger\Annotation\ApiOperation;
# 参数组的注解
use joyqhs\Swagger\Annotation\ApiParams;
# 参数的注解
use joyqhs\Swagger\Annotation\ApiParam;
# 响应注解
use joyqhs\Swagger\Annotation\ApiResponses;

参数说明

参数

注解	参数名称	说明	其他
Api	name	分组名称
ApiOperation	name	接口名称
ApiOperation	desc	接口描述
ApiParams	name	参数组名称
ApiParams	value	参数组	数组,多个ApiParam 或者 ApiParams
ApiParam	name	参数名
ApiParam	desc	参数描述
ApiParam	type	参数类型 integer string ....
ApiParam	required	是否必填 true or false
ApiParam	children	子参数 ， 一般用于响应结果的多维数组	数组 多个 ApiParam
ApiResponses	value	响应组	数组,多个ApiParam 或者 ApiParams

配置

php bin/hyperf.php vendor:public joyqhs/hyperf-swagger

在 config/autoload/swagger.php 中简单配置

使用例子

<?php

declare(strict_types=1);

namespace App\Controller;

use Hyperf\Di\Annotation\Inject;
use Hyperf\HttpServer\Annotation\Controller;
use Hyperf\HttpServer\Annotation\Controller;
use Hyperf\HttpServer\Annotation\DeleteMapping;
use Hyperf\HttpServer\Annotation\GetMapping;
use Hyperf\HttpServer\Annotation\Middleware;
use Hyperf\HttpServer\Annotation\PostMapping;
use Hyperf\HttpServer\Annotation\PutMapping;
use Hyperf\HttpServer\Contract\RequestInterface;
use Hyperf\HttpServer\Contract\ResponseInterface;
use hyperfai\Swagger\Annotation\Api;
use hyperfai\Swagger\Annotation\ApiOperation;

#[Controller()]
#[Api('系统设置')]
class AuthController extends AbstractController
{
    
    #[PostMapping(path: '/api/login')]
    #[ApiOperation(module: '用户管理', name: '用户登陆', desc: '用户登陆')]
    public function login($id)
    {

    }
    
    #[PostMapping(path: '/api/logout')]
    #[ApiOperation(module: '用户管理', name: '退出登陆', desc: '退出登陆')]
    public function logout(){

    }
    
}

查看接口

 php bin/hyperf.php swagger:gen 

可指定参数 -S server.php 中的服务名称 默认 http -P 路由地址 -E 导出

命令行

 php bin/hyperf.php swagger:gen  -S admin
 php bin/hyperf.php swagger:gen  -P auth/login
 php bin/hyperf.php swagger:gen  -S admin -E 

展示

注

目前仅支持导出 easydoc.xyz 的 json api文件 可以在 easydoc.xyz 中导入 实现模拟请求等 后期会支持更多和内置接口展示。