装不上 zircote/swagger-php 主因是 php 版本过低（需 ≥7.4 或 ≥8.0）或未启用 json、mbstring 扩展；注释生成空文档因缺少 @oa\openapi 根节点或命名空间错误；v5 版本起须改用 #[oa\get] 属性语法，旧 docblock 注释无效。
composer require zircote/swagger-php 装不上？先确认 PHP 版本和扩展
装不上 zircote/swagger-php 最常见的原因是 PHP 版本太低或缺少 json 扩展。它要求 PHP ≥ 7.4（v4.x）或 ≥ 8.0（v5.x），且必须启用 json 和 mbstring —— 这两个不是可选，是硬依赖。
实操建议：
- 运行
php -v确认版本；php -m | grep -E 'json|mbstring'检查扩展是否加载 - 如果用 Docker，确保
Dockerfile里有docker-php-ext-install json mbstring - 某些共享主机禁用
exec()，而swagger-php的 CLI 模式会调用php子进程 —— 此时只能用编程式调用，不能用vendor/bin/openapi
注释写完却生成空文档？检查 @OA\OpenApi 根节点和命名空间
swagger-php 不是“扫所有注释就出文档”，它必须找到一个顶层的 @OA\OpenApi 注解作为入口，且该注解所在文件需被扫描到。常见错误是注释写了，但没挂载根节点，或用了错误的命名空间。
实操建议：
- 在项目入口文件（如
public/index.php或单独建openapi.php）中加一个空的@OA\OpenApi注解，例如：<?php /** * @OA\OpenApi( * @OA\Info(title="API", version="1.0.0") * ) */
- 确保所有
@OA\*注解都使用完整命名空间：写@OA\Get，别写@Get（除非已use OpenApi\Annotations as OA;） - 执行扫描时指定路径：
vendor/bin/openapi app/Controller/ --output docs/openapi.json，别只扫app/却漏掉src/或api/
生成的 JSON 缺少服务器地址或请求体？@OA\Server 和 @OA\RequestBody 必须显式声明
swagger-php 不会自动推断 servers 或 requestBody.content 类型。如果你看到生成的 openapi.json 里 servers 是空数组、或 POST 接口没有 schema 描述，大概率是漏了关键注解。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
实操建议：
-
@OA\Server必须写在@OA\OpenApi内部，或作为独立注解放在能被扫描到的文件里；单写@OA\Server(url="https://api.example.com")不生效，得嵌套：/** * @OA\OpenApi( * @OA\Info(...), * @OA\Server(url="https://api.example.com") * ) */
-
@OA\Post下必须配@OA\RequestBody，且里面至少有一个@OA\JsonContent或@OA\MediaType，否则 Swagger UI 会显示 “No request body defined” - 别指望从 PHP 类型反射自动补全 schema：
public function store(Request $request)不会自动生成Request结构，得手动写@OA\JsonContent(ref="#/components/schemas/UserInput")
升级到 swagger-php v5 后注解报错？注意命名空间和注解语法变化
v5 把所有注解类从 OpenApi\Annotations\* 移到了 OpenApi\Attributes\*，且强制使用 PHP 8+ 的 Attribute 语法。如果你还在用 @OA\Get 这种 docblock 风格，v5 会完全忽略它们。
实操建议：
- v5 只认 Attribute 写法：
#[OA\Get(path: '/users')] public function index() { ... }，旧的/** @OA\Get(...) */注释无效 - 如果项目还混着 PHP 7.4，别升 v5 —— 直接锁死
"zircote/swagger-php": "^4.9" - v5 的
vendor/bin/openapi默认只扫描 Attribute，如需兼容旧注释，加--legacy参数（但不推荐，只是过渡）
实际用起来最麻烦的不是写注释，而是让扫描器准确覆盖所有带 @OA* 的文件路径，同时又不把 vendor 或测试文件卷进去。路径配错一毫秒，文档就少一半接口。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
