PHP怎么写一个简单的API文档-php教程-PHP中文网

php本身不自带api文档生成器，需通过注释（如phpdoc）配合工具（swagger、apigen等）或自定义脚本解析生成html/json等格式文档；轻量场景可手写php脚本提取@method、@url、@param等标签生成静态html，超50接口或复杂路由时应切换至zircote/swagger-php等标准方案。

php怎么写一个简单的api文档

用 PHP 生成 API 文档要先明确输出目标

PHP 本身不自带 API 文档生成器，你不是在“用 PHP 写文档”，而是在用 PHP 生成文档内容（比如 HTML、Markdown 或 JSON），或配合工具（如 Swagger、ApiGen）注入注释后自动生成。最轻量且可控的做法是：用 PHP 脚本读取接口代码中的注释，按约定格式输出 HTML 页面。

关键判断：如果你只是想快速给内部同事看几个接口怎么调，别碰 Swagger UI 那套配置；直接手写一个 api-docs.php，读取 routes/ 下的控制器方法注释，拼成表格就行。

从 PHP 注释里提取接口信息的实操方式

PHPDoc 是最稳妥的来源，但必须统一格式，否则解析会漏或错。建议只解析三类标签：@method（HTTP 方法）、@url（路径）、@param（参数说明），忽略 @return 这类非请求必需字段。

btpanel phpsite 宝塔面板PHP网站

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

下载

所有接口方法必须加 /** */ 块注释，且第一行不能空
@method POST 和 @url /v1/users 必须独占一行，不能和别的标签混写
不要依赖反射自动读取参数类型——PHP 8.0+ 的联合类型（如 string|int）会让正则崩溃，直接靠人工写 @param user_id int 用户ID
示例中用 file_get_contents() 读控制器文件，再用 preg_match_all() 提取注释块，比用 ReflectionMethod 更稳定

/**  
 * @method GET  
 * @url /v1/posts  
 * @param page int 页码，默认1  
 */  
public function listPosts() { ... }

生成 HTML 文档时绕不开的兼容性坑

生成的 HTML 页面如果被多个团队访问，要注意两点：一是路径引用不能硬编码，二是 CSS 不能依赖外部 CDN（内网可能打不开）。最简方案是把样式内联进 <style></style>，JS 只留折叠/搜索功能，且用原生 JS（避开 jQuery 兼容问题）。

<link href="https://cdn.example.com/style.css"> → 改成内联 <style>table{border-collapse:collapse}...</style>
搜索框用 input[type="search"] + oninput 事件过滤 DOM 表格行，不发请求、不依赖后端
URL 路径里的变量占位符（如 /users/{id}）要转义成 {id}，否则浏览器解析 HTML 时会被当成标签
生成的 HTML 文件名固定为 api-docs.html，放在 Web 根目录下，避免用 api-docs.php 动态生成——Nginx 默认不执行 .html 里的 PHP

什么时候该放弃手写 PHP 脚本

当你的项目开始用 Laravel 或 Symfony，且路由定义分散在 YAML、注解、闭包里时，手写解析脚本维护成本会指数上升。这时直接切到 zircote/swagger-php + swagger-ui 组合更省事。

在控制器方法上加 @OA\Get、@OA\Parameter 注解，比自定义 @url 标签更标准
php vendor/bin/openapi app/ --output docs/openapi.json 生成 OpenAPI 3.0 文件，比自己拼 JSON 稳定
把 openapi.json 丢进 Swagger UI 的 index.html 就能跑，不用 PHP 环境也能看文档
但注意：Laravel 的 Route::apiResource() 不会自动产生 OpenAPI 注解，得手动补全，不然文档里看不到 POST /posts 这种隐式路由