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),文档的生成主要依赖注释。
先看效果图:
下面演示下如何在 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