Hyperf Swagger 如何使用？

Question

根据 https://hyperf.wiki/3.1/#/zh-cn/swagger?id=hyperf-swagger 官方文档安装配置，但是文档太简单了，出了问题不知道怎么排查，网络文章写的也让人摸不着头脑，不知道别人的json 是怎么生成的。

swagger.php 配置

return [
  'enable' => true,
  'port' => 9500,
  'json_dir' => BASE_PATH . '/storage/swagger',
  'html' => null,
  'url' => '/swagger',
  'auto_generate' => true,
  'scan' => [
    'paths' => null,
  ],
  'processors' => [
    // users can append their own processors here
  ],
  'server' => [
    'http' => [
      'servers' => [
        [
          'url' => 'http://127.0.0.1:9501',
          'description' => 'Test Server',
        ],
      ],
      'info' => [
        'title' => 'Sample API',
        'description' => 'This is a sample API using OpenAPI 3.0 specification',
        'version' => '1.0.0',
      ],
    ],
  ],
];

controller 文件配置

#[SA\HyperfServer('http')]
class IndexController extends AbstractController
{
    #[SA\Post(path: '/test', summary: 'POST 表单示例', tags: ['Api/Test'])]
    #[SA\Response(response: 200, description: '返回值的描述')]
    public function index()
    {        
    }

以上配置 使用命令 php bin/hyperf.php gen:swagger ，提示 Generate swagger json success. 但是并没有生成文件

请问我的配置是哪里有问题？

Answer 1

我看了一下你的配置，scan 配置中的 paths 需要指定要扫描的路径。目前你设置为 null，将 paths 设置为一个包含你希望扫描的目录的数组

return [
  'enable' => true,
  'port' => 9500,
  'json_dir' => BASE_PATH . '/storage/swagger',
  'html' => null,
  'url' => '/swagger',
  'auto_generate' => true,
  'scan' => [
    'paths' => [
      BASE_PATH . '/app/Controller',
    ],
  ],
  'processors' => [
    // users can append their own processors here
  ],
  'server' => [
    'http' => [
      'servers' => [
        [
          'url' => 'http://127.0.0.1:9501',
          'description' => 'Test Server',
        ],
      ],
      'info' => [
        'title' => 'Sample API',
        'description' => 'This is a sample API using OpenAPI 3.0 specification',
        'version' => '1.0.0',
      ],
    ],
  ],
];

还有一点json_dir这个指向的目录有无写入权限

补充

在控制器中使用注解： 使用 Hyperf\Swagger\Annotation 提供的注解来标注你的 API 接口。

use Hyperf\Swagger\Annotation as SA;

#[SA\HyperfServer('http')]
class IndexController extends AbstractController
{
    #[SA\Post(path: '/test', summary: 'POST 表单示例', tags: ['Api/Test'])]
    #[SA\Response(response: 200, description: '返回值的描述')]
    public function index()
    {
        // Your code here
    }
}

Answer 2

我的情况和这个老哥的情况是一样的https://github.com/hyperf/hyperf/issues/5601

问题已经解决

swagger 配置文件

return [
  'enable' => true,
  'port' => 9500,
  'json_dir' => BASE_PATH . '/storage/swagger',
  'html' => null,
  'url' => '/swagger',
  'auto_generate' => true,
  'scan' => [
    'paths' => null,
  ]
];

controller

use Hyperf\Swagger\Annotation as SA;
#[SA\HyperfServer('http')]
class IndexController extends AbstractController
{
    #[SA\Post(path: '/test', summary: 'POST 表单示例', tags: ['Api/Test'])]
    #[SA\Response(response: 200, description: '返回值的描述')]
    public function test()
    {
        return "123";
    }
}

如果生成不了也不报错的情况可以试试

 use Hyperf\Swagger\Annotation\Get;
 use Hyperf\Swagger\Annotation\HyperfServer;
 #[HyperfServer('http')]
 #[Get(path: '/index/index')]