程序员往往是人格分裂的。
我们即痛恨在没有文档的前提下做开发与维护。
还懒得写文档。
于是swagger 的出现，
一 先盗张图，说明一下咋自动生成文档 .
二 swagger 整备
2.1 安装
composer require hyperf/swagger
2.2 配置
php bin/hyperf.php vendor:publish hyperf/swagger
bash-5.1# php bin/hyperf.php vendor:publish hyperf/swagger
[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.
[hyperf/swagger] publishes [config] successfully.
成功后，生成文件。 config\autoload\swagger.php
<?php
declare(strict_types=1);
/**
* This file is part of Hyperf.
*
* @link https://www.hyperf.io
* @document https://hyperf.wiki
* @contact group@hyperf.io
* @license https://github.com/hyperf/hyperf/blob/master/LICENSE
*/
return [
'enable' => true,
'port' => 9500,
'json_dir' => BASE_PATH . '/storage/swagger',
'html' => null,
'url' => '/swagger',
'auto_generate' => true,
'scan' => [
'paths' => null,
],
];
2.3 swagger
从2.2 发现端口是9500.
在容器内访问ok
于是改docker-compose.yaml 将9500 端口给暴露出来，用于查看swagger
完整的docker-compose 配置已查看 juejin.cn/post/724745…
这里，对Dockerfile 和docker-compose.yaml 进行修改
hyperf/Dockerfile
EXPOSE 9501 9500
docker-compose.yaml
ports:
- "9501:9501"
- "9500:9500"
停服务，删旧镜像，重新compose up
docker-compose down
[+] Running 5/5
- Container mysql Removed 2.0s
- Container redis Removed 0.6s
- Container hyperf Removed 10.4s
- Container nginx Removed 0.8s
- Network docker-compose_xuxing Removed 0.2s
docker rmi docker-compose_hyperf:latest
docker-compose up -d
docker ps |grep hyperf
5c305cdf473a docker-compose_hyperf "php /data/project/a…" 44 seconds ago Up 42 seconds 0.0.0.0:9500-9501->9500-9501/tcp hyperf
打开浏览器，http://127.0.0.1:9500/swagger
后续发布至生产时，nginx 给个server_name 再设一下proxy_pass 即可。
location / {
proxy_pass http://172.88.0.84:9500;
听说 docker 下用 traefik 更合适，目前项目小，先用nginx 顶起来，改天再研究traefik
说个全栈原则，技术学不完的，非重点部分，有可用的方案先用着，闲下来了再研究。真到生产了，运维这种专业的事交专业的人来做。
但是，一定要搞出来。方法土鳖就土鳖，这个是底线。
三 使用。
3.1 照着文档抄了下代码 。
use Hyperf\Swagger\Annotation as OA;
#[OA\HyperfServer('http')]
class ApplyController extends AbstractController
{
#[Inject]
protected ApplyService $applyService;
#[Inject]
protected DbHelper $dbHelper;
#[OA\RequestBody(
description: '请求参数',
content: [
new OA\MediaType(
mediaType: 'application/json',
schema: new OA\Schema(
required: ['username', 'age'],
properties: [
new OA\Property(property: 'username', description: '用户名字段描述', type: 'string'),
new OA\Property(property: 'age', description: '年龄字段描述', type: 'string'),
new OA\Property(property: 'city', description: '城市字段描述', type: 'string'),
]
),
),
],
)]
#[OA\Response(response: 200, description: '返回值的描述')]
public function apply()
{
3.2 进入容器，生成一下 gen:swagger
php bin/hyperf.php gen:swagger
PHP Fatal error: Constant expression contains invalid operations in /data/project/api.xuxing.tech/app/Controller/ApplyController.php on line 48
不出意外的出了意外 ，文档写的足够简单，看不出啥东西， 开启排坑模式
从官网文档中找到链接。 zircote.github.io/swagger-php…
看文档时发现，install 为
composer require zircote/swagger-php
找到代码 ，看了下composer.json，就是同一个东西。
各种尝试后，还是不出来，json 也没有。能力不足，不参与这种深入排坑，换一个。 gitee.com/lphkxd/hype…
文档看着很爽，一动手。
composer require mzh/hyperf-swagger
Info from https://repo.packagist.org: #StandWithUkraine
./composer.json has been updated
Running composer update mzh/hyperf-swagger
Loading composer repositories with package information
Updating dependencies
Your requirements could not be resolved to an installable set of packages.
Problem 1
- mzh/hyperf-swagger v0.1.0 requires hyperf/validation ~2.0.0 -> satisfiable by hyperf/validation[v2.0.0, ..., 2.0.x-dev].
- mzh/hyperf-swagger[dev-master, v0.1.1, ..., v0.1.3, v1.0.0, ..., v1.0.11] require mzh/hyperf-helper ^0.1.0 -> satisfiable by mzh/hyperf-helper[v0.1
.0, ..., v0.1.7].
- hyperf/validation[v2.0.0, ..., v2.0.22] require hyperf/command ~2.0.0 -> found hyperf/command[v2.0.0, ..., 2.0.x-dev] but it conflicts with your ro
ot composer.json require (~3.0.0).
- hyperf/validation[v2.0.24, ..., 2.0.x-dev] require hyperf/contract ~2.0.0 -> found hyperf/contract[v2.0.0, ..., 2.0.x-dev] but the package is fixed
to v3.0.10 (lock file version) by a partial update and that version does not match. Make sure you list it as an argument for the update command.
- mzh/hyperf-helper[v0.1.0, ..., v0.1.7] require hyperf/utils ~2.0.0 -> found hyperf/utils[v2.0.0, ..., 2.0.x-dev] but the package is fixed to v3.0.1
8 (lock file version) by a partial update and that version does not match. Make sure you list it as an argument for the update command.
- Root composer.json requires mzh/hyperf-swagger * -> satisfiable by mzh/hyperf-swagger[dev-master, v0.1.0, v0.1.1, v0.1.2, v0.1.3, v1.0.0, ..., v1.0
.11, 9999999-dev].
Use the option --with-all-dependencies (-W) to allow upgrades, downgrades and removals for packages currently locked to specific versions.
You can also try re-running composer require with an explicit version constraint, e.g. "composer require mzh/hyperf-swagger:*" to figure out if any versi
on is installable, or "composer require mzh/hyperf-swagger:^2.1" if you know which you need.
Installation failed, reverting ./composer.json and ./composer.lock to their original content.
再换一个。 github.com/daodao97/ap…
今天算是爬不出坑了， 明天继续 。
接着来。
中午接完孩子,想着swagger 不出来，相当不爽，仔细想了一下，把乱七八糟的删了，直接用官网的， 直接进去debug Generator ，看下日志为啥不出来。
一轮折腾后，发现官网提供的例子有坑，直接抄有bug. 不停的报。
PHP Fatal error: Constant expression contains invalid operations in
换个方式，就ok 了。
/**
* @OA\Get(
* path="/api/resource.json",
* @OA\Response(response="200", description="An example resource")
* )
*/
仔细想了一下，config 也有类似问题。 应该是我环境对注解不太支持引发的。 后续有空再研发。
