PHPJSON如何生成接口文档_php用json自动输出api说明的技巧【解答】

php生成json接口文档时必须使用json_unescaped_unicode避免中文乱码，配合json_pretty_print需用|拼接；需设置content-type头防止浏览器渲染异常；写入静态文件应加锁或原子替换；注释不可替代运行时采样。

PHP 生成 JSON 接口文档时，json_encode() 的 JSON_UNESCAPED_UNICODE 必须加

中文字段名或描述一出现就乱码，不是 PHP 版本问题，是默认转义 Unicode 导致的。不加这个 flag，接口文档里看到的是 "u6570u636e" 而不是 "数据"。

• 所有含中文的文档结构（如 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 给目录足够

生成文档这件事，最难的从来不是怎么输出 JSON，而是怎么让字段含义、必填逻辑、异常码这些“非结构信息”也稳定落地。手动维护容易过期，全自动又容易失真。折中点：用代码扫描 + 关键字段人工标注，比纯自动靠谱得多。