如何利用ThinkPHP实现API接口的Swagger文档生成【扩展】-ThinkPHP-PHP中文网

推荐使用官方扩展 topthink/think-swagger，通过解析 route::rule() 和控制器 @oa 注解自动生成 openapi 3.0 格式的 /api/doc/swagger.json；需显式定义路由、php ≥ 7.4、控制器方法含正确 @oa\get 等标签及参数注解，生产环境须关闭 swagger.enable。

如何利用thinkphp实现api接口的swagger文档生成【扩展】

ThinkPHP 6 如何自动扫描路由生成 Swagger JSON

原生 ThinkPHP 不带 Swagger 文档生成功能，必须依赖扩展或手动构造 JSON。推荐使用 topthink/think-swagger（官方维护的轻量扩展），它通过解析 Route::rule() 和控制器注解，自动生成符合 OpenAPI 3.0 规范的 /swagger.json。

安装后需在 app/middleware.php 中注册中间件，并确保所有 API 路由都通过 Route::group() 显式定义——动态闭包路由、未命名路由或未绑定控制器方法的规则会被跳过。

控制器方法必须有 PHPDoc 注释，至少包含 @api 或 @OA\Get 等 OpenAPI 标签（用 zircote/swagger-php 语法）
不支持 __call 动态方法、匿名函数路由、Route::import() 加载的外部路由文件
swagger.json 默认输出路径为 /api/doc/swagger.json，可通过配置项 swagger.output_path 修改

控制器里怎么写注解才能被正确识别

Swagger 扩展只认标准 @OA\ 注解（来自 zircote/swagger-php），不是随便写个 @param 就能生效。最简可用模板如下：

/**
 * @OA\Get(
 *     path="/api/user/{id}",
 *     summary="获取用户详情",
 *     @OA\Parameter(
 *         name="id",
 *         in="path",
 *         required=true,
 *         @OA\Schema(type="integer")
 *     ),
 *     @OA\Response(response="200", description="成功")
 * )
 */
public function read($id) { ... }

常见失效原因：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

漏写 @OA\Get / @OA\Post 等顶层操作标签（仅写 @param 不触发解析）
参数 in 值写成 "url" 或 "query"（正确是 "path" / "query" / "header"）
返回模型用了 @OA\Schema(ref="#/components/schemas/User")，但没在类顶部定义 @OA\Schema 组件
PHP 版本低于 7.4 —— zircote/swagger-php v4 要求 PHP ≥ 7.4

如何让 Swagger UI 页面和 ThinkPHP 后端同域名访问

扩展默认只提供 /api/doc/swagger.json 接口，不带 UI。要集成 UI，不能直接扔一个 index.html 进 public/ 然后硬编码 URL，否则跨域或 basePath 错位会导致请求 404。

正确做法是：用 ThinkPHP 的 view 渲染 Swagger UI 模板，动态注入 window.onload 中的 url 为相对路径 ./swagger.json；同时确保 Nginx/Apache 开启 Access-Control-Allow-Origin: * 或明确指定前端域名。

不要把 Swagger UI 的 dist/ 整体复制到 public/ 并用静态路径访问——这样无法动态切换环境（如测试服指向 /test/swagger.json）
若启用多模块（如 api 模块），需在 config/swagger.php 中设置 'base_path' => '/api'，否则生成的路径会漏前缀
生产环境务必关闭 swagger.enable 配置，避免暴露内部接口结构

为什么 /swagger.json 返回 500 但日志没报错

典型原因是注解语法错误导致 zircote/swagger-php 解析器静默失败（不抛异常，返回空数组），最终 JSON 编码时遇到 null 报 json_encode() expects parameter 1 to be string, array given 类似错误，但框架已捕获并返回 500，而日志级别不够看不到底层 warning。