php生成json接口文档时必须使用json_unescaped_unicode避免中文乱码，配合json_pretty_print需用|拼接；需设置content-type头防止浏览器渲染异常；写入静态文件应加锁或原子替换；注释不可替代运行时采样。
PHP 生成 JSON 接口文档时，json_encode() 的 JSON_UNESCAPED_UNICODE 必须加
中文字段名或描述一出现就乱码，不是 PHP 版本问题，是默认转义 Unicode 导致的。不加这个 flag，接口文档里看到的是 "\u6570\u636e" 而不是 "数据"。
- 所有含中文的文档结构（如
title、description、param字段）都得用json_encode($doc, JSON_UNESCAPED_UNICODE) - 如果还用了
JSON_PRETTY_PRINT，两个 flag 要用 | 拼接：JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT - PHP 5.4+ 才支持
JSON_UNESCAPED_UNICODE，低于这个版本得自己写递归替换\uXXXX，不推荐
用 ReflectionClass 自动提取方法注释生成文档，但别信 @return 里的类型
很多人想靠注释自动生成参数列表和返回说明，ReflectionClass 确实能读 @param 和 @desc，但实际接口返回结构往往和注释对不上——尤其是数组嵌套、动态 key、空值处理这些地方。
-
@param string $id只能告诉你传字符串，但不会说明它是否允许为空、是否要校验长度、是否需 base64 编码 - 真正可靠的返回结构，得从实际调用结果里采样：
json_encode($api->getUser(123), JSON_UNESCAPED_UNICODE)，再截取前几条做 schema 示例 - 注释只适合作为补充说明，不能替代运行时数据；把注释当契约，上线后十有八九要返工
生成文档时，Content-Type: application/json 头漏设，前端看到的是源码而不是格式化 JSON
浏览器直接访问 PHP 脚本输出 JSON，没设 header 就会当成 text/html 渲染，显示一堆没换行没缩进的原始字符，连折叠都做不到。
- 必须在
echo json_encode(...)前加：header('Content-Type: application/json; charset=utf-8'); - 如果用了
var_dump()或print_r()调试过，后面忘了删，会导致 header 发送失败，整个文档变成空白或报错Cannot modify header information - Nginx + PHP-FPM 环境下，若启用了
fastcgi_buffering on，可能缓存响应头，导致 header 不生效——临时关掉它验证
用 file_put_contents() 写入静态 JSON 文档，注意权限和并发覆盖风险
有些项目图省事，每次请求都重写一个 api-docs.json 文件，结果高并发时文档变空或结构损坏。
立即学习“PHP免费学习笔记（深入）”；
- 不要直接
file_put_contents('api-docs.json', $json)，改用file_put_contents('api-docs.json', $json, LOCK_EX)加写锁 - 写入前先生成临时文件（如
api-docs.json.tmp），写完再rename()替换，保证原子性 - 确保 Web 服务器用户（如 www-data）对目录有写权限，但别给 777 ——
644给文件、755给目录足够
