限时 5折! 详情

hyperf 实战之 swagger 文档

2099 0 0

今天我们一起看下 hyperf 框架内是怎么使用 swagger 文档的。

市面上可选择的接口文档很多,像 ShowDoc、Postman、Apipost、eolink 等等,有些是支持本地化部署的,有些是云上操作的,大家可以自己去选择。

今天我们要介绍的是可以在线生成的、可视化的 api 文档 swagger,swagger 官网参考 https://swagger.io/。

hyperf 官方在 3.0.* 也对 swagger 做了支持,参考 hyperf/swagger 组件(https://github.com/hyperf/swagger) ,其本质还是 zircote/swagger-php (https://github.com/zircote/swagger-php),文档的生成主要依赖注释。

先看效果图:

fadd512dfe-openapi.png

下面演示下如何在 hyperf 框架内使用 swagger 文档。

1、安装 hyperf/swagger 组件

composer require hyperf/swagger:3.0.0

2、全局配置

去购买

还有91%的精彩内容,购买继续阅读

登录 后发布评论
  • 这玩意有点麻烦 ,写那么多注解 还不如 apipost方便

    • +1 ruoyi用swagger是因为他有自动生成 hyperf不自动生成太麻烦了

  • 大佬,我生成JSON文件时报错:Call to undefined method Doctrine\Common\Annotations\AnnotationRegistry::registerLoader() in xxx/vendor/zircote/swagger-php/src/Analyser.php:14
    请问要怎么解决?

    • 我跟你一样的问题,你解决了吗?

    • 记录解决时候的情形
      1.发现 doctrine/annotation包中final class AnnotationRegistry类下面并没registerLoader()方法,查看github上的发版记录发现2.0已经被废弃
      2.尝试将doctrine/annotation降低版本 composer require doctrine/annotations:1.14.0 -W
      但是被friendsofphp/php-cs-fixer包锁定版本为2.0以上,我只能修改composer.lock中 friendsofphp/php-cs-fixer包的require限制,将设置为"doctrine/annotations": "*"
      3.继续运行 composer require doctrine/annotations:1.14.0 -W 方才解决问题,可以正常生成json,但是取消了包限制不知道会不会有问题

  • bash-5.1# composer require hyperf/swagger:3.0.0 -W
    ./composer.json has been updated
    Running composer update hyperf/swagger --with-all-dependencies
    Loading composer repositories with package information
    /......
    bash-5.1# php bin/hyperf.php swagger:gen -p 'app/Controller' -f 'json'
    [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\Config\Listener\RegisterPropertyHandlerListener listener.
    [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\ExceptionHandler\Listener\ErrorExceptionHandler listener.
    [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\ExceptionHandler\Listener\ExceptionHandlerListener listener.
    [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\DbConnection\Listener\RegisterConnectionResolverListener listener.
    Call to undefined method Doctrine\Common\Annotations\AnnotationRegistry::registerLoader()
    [ERROR] Error: Call to undefined method Doctrine\Common\Annotations\AnnotationRegistry::registerLoader() in /data/project/vendor/zircote/swagger-php/src/Analyser.php:14
    Stack trace:
    //......
    bash-5.1#

    hyperf/swagger:3.0.0 -W 大佬,还是报错

  • bash-5.1# php bin/hyperf.php gen:swagger -p 'app/Controller' -f 'json'
    [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\Config\Listener\RegisterPropertyHandlerListener listener.
    [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\ExceptionHandler\Listener\ErrorExceptionHandler listener.
    [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\Swagger\Listener\BootSwaggerListener listener.
    [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\ExceptionHandler\Listener\ExceptionHandlerListener listener.
    [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\DbConnection\Listener\RegisterConnectionResolverListener listener.


    The "-p" option does not exist.


    gen:swagger [--disable-event-dispatcher]

    bash-5.1#

    麻烦大佬看一下哈

    • 文章仔细看了吗?明明写的是 swagger:gen,不知道你的 gen:swagger 哪里来的。

    • [root@gometer ~]# docker exec -it hyperfApi /bin/bash
      bash-5.1# cd /data/project/
      bash-5.1# php bin/hyperf.php swagger:gen -p 'app/Controller' -f 'json'
      [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\Config\Listener\RegisterPropertyHandlerListener listener.
      [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\ExceptionHandler\Listener\ErrorExceptionHandler listener.
      [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\Swagger\Listener\BootSwaggerListener listener.
      [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\ExceptionHandler\Listener\ExceptionHandlerListener listener.
      [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\DbConnection\Listener\RegisterConnectionResolverListener listener.


      There are no commands defined in the "swagger" namespace.


      bash-5.1#
      换成swagger:gen也是报错,都是一步一步按照教程操作哦

  • bash-5.1# php bin/hyperf.php swagger:gen -p 'app/Controller' -f 'json'
    [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\Config\Listener\RegisterPropertyHandlerListener listener.
    [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\ExceptionHandler\Listener\ErrorExceptionHandler listener.
    [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\Swagger\Listener\BootSwaggerListener listener.
    [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\ExceptionHandler\Listener\ExceptionHandlerListener listener.
    [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\DbConnection\Listener\RegisterConnectionResolverListener listener.


    There are no commands defined in the "swagger" namespace.


    bash-5.1#
    大佬,生成swagger的 json 文件报错,如何解决呀

    • 你是不是没有安装 hyperf/swagger 组件? composer info | grep hyperf/swagger 查下

    • 安装了hyperf/swagger 组件,不知道为什么报 There are no commands defined in the "swagger" namespace.
      bash-5.1# composer info | grep hyperf/swagger
      hyperf/swagger v3.0.7 A swagger library for Hyperf.
      bash-5.1#
      bash-5.1# php bin/hyperf.php swagger:gen -p 'app/Controller' -f 'json'
      [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\Config\Listener\RegisterPropertyHandlerListener listener.
      [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\ExceptionHandler\Listener\ErrorExceptionHandler listener.
      [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\Swagger\Listener\BootSwaggerListener listener.
      [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\ExceptionHandler\Listener\ExceptionHandlerListener listener.
      [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\DbConnection\Listener\RegisterConnectionResolverListener listener.


      There are no commands defined in the "swagger" namespace.


      bash-5.1#

    • 看了一下,是 hyperf/swagger 版本的问题。3.0.7 改动比较大且尚不稳定,文中的操作适合 3.0.0 的版本。你先把 hyperf/swagger 的版本降到 3.0.0 吧(composer require hyperf/swagger:3.0.0 -W)。

    • bash-5.1# composer require hyperf/swagger:3.0.0 -W
      ./composer.json has been updated
      Running composer update hyperf/swagger --with-all-dependencies
      Loading composer repositories with package information
      /......
      bash-5.1# php bin/hyperf.php swagger:gen -p 'app/Controller' -f 'json'
      [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\Config\Listener\RegisterPropertyHandlerListener listener.
      [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\ExceptionHandler\Listener\ErrorExceptionHandler listener.
      [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\ExceptionHandler\Listener\ExceptionHandlerListener listener.
      [DEBUG] Event Hyperf\Framework\Event\BootApplication handled by Hyperf\DbConnection\Listener\RegisterConnectionResolverListener listener.
      Call to undefined method Doctrine\Common\Annotations\AnnotationRegistry::registerLoader()
      [ERROR] Error: Call to undefined method Doctrine\Common\Annotations\AnnotationRegistry::registerLoader() in /data/project/vendor/zircote/swagger-php/src/Analyser.php:14
      Stack trace:
      //......
      bash-5.1#

      hyperf/swagger:3.0.0 -W 大佬,还是报错

    • 遇到了相同的问题,你的处理好了吗?

  • 大佬 docker 里 git clone 好像有点不得劲 unable to access 'https://github.com/swagger-api/swagger-ui.git/': HTTP/2 stream 1 was not closed cleanly before end of the underlying stream