需确保swagger-ui正确加载openapi.json且不冲突：用zircote/swagger-php注解生成文档，配置autoload路径，指定绝对输出路径；静态托管swagger-ui至public/swagger，修改index.html的url指向；openapi.json须直曝public目录，避免中间件干扰，并动态注入servers字段。
直接在 Composer API 项目里加 Swagger，不是装个包就完事——关键得让 swagger-ui 能正确加载你生成的 openapi.json，且不和现有路由冲突。
用 zircote/swagger-php 注解生成 OpenAPI 文档
这是目前最主流的 PHP 注解式方案，不侵入业务逻辑，但必须确保 CLI 生成命令能读到你的控制器类。常见错误是运行 php -d extension=opcache.so vendor/bin/openapi 时提示“找不到类”，本质是自动加载没生效或路径指定错。
- 在
composer.json的autoload或autoload-dev中确认已包含 API 控制器所在目录，例如："app/Http/Controllers" - 生成命令建议加
--output并指定绝对路径，避免相对路径导致后续 Web 访问 404：vendor/bin/openapi app/Http/Controllers --output public/openapi.json - 注解要写在类、方法或参数上，
@OA\Get和@OA\Response必须成对出现，否则 JSON 校验失败
用 swagger-api/swagger-ui 提供前端界面（静态托管）
别用 Composer 安装 swagger-api/swagger-ui——它只是前端资源，Composer 安装会混进 vendor，Web 服务器默认不公开该目录。正确做法是把 dist 文件夹复制到 public/swagger 下。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 下载最新 release 的
swagger-ui-distZIP，解压后只取dist/内容，放至public/swagger/ - 在
public/swagger/index.html中修改url指向：url: "/openapi.json"（注意路径与上一步生成位置一致） - 确保 Laravel/Lumen 等框架没有把
/swagger路由拦截，例如 Lumen 需检查bootstrap/app.php中是否禁用了静态文件服务
绕过路由层，直接暴露 openapi.json（Laravel 示例）
很多项目试图用控制器返回 JSON，结果触发中间件（如 JWT 验证）、响应格式封装（如 response()->json() 包裹），导致 Swagger UI 加载失败或报 SwaggerUIBundle is not defined。
- 不要走 MVC 流程：在
public/目录下直接生成并保留openapi.json，由 Web 服务器原样返回 - 如果必须动态生成（如多环境切换 host），可用一个极简脚本放在
public/gen-openapi.php，仅做include和echo json_encode(...)，不引入框架启动逻辑 - 检查响应头：
Content-Type必须是application/json，Nginx/Apache 默认对.json后缀已支持，无需额外配置
最容易被忽略的是 OpenAPI JSON 中的 servers 字段——本地开发写 http://localhost:8000，上线后忘了改，Swagger UI 发出的请求全 404。建议用环境变量注入，或生成脚本中根据 APP_ENV 动态拼接。
