PHP项目接口文档怎么写

本文目录导读：

1. 方案一：轻量级——Markdown 文档（适合中小型项目、快速迭代）
2. 分页参数
3. 方案三：辅助工具类（实用派）
4. 高级建议（避坑指南）

为 PHP 项目编写接口文档，核心目标是让前端、客户端或第三方开发者能快速、准确地对接，没有统一的强制标准，但遵循行业惯例能大大提升协作效率。

这里提供一套最实用、最规范的编写方案，结合了 Markdown 文档（轻量） 和 OpenAPI/Swagger（重量级） 两种模式，你可以根据项目规模选择。

---

轻量级——Markdown 文档（适合中小型项目、快速迭代）

这是最直接的方式,维护在 Git 仓库中（如 docs/api.md），随代码版本控制。

文档头部（全局说明）

首先定义全局的通用规则,避免每个接口重复书写。

# 项目名称 API 接口文档
**版本号：** v1.0  
**更新日期：** 2023-10-01  
**Base URL：** `https://api.example.com`  
**协议格式：** HTTPS + JSON
---
## 全局约定
### 1. 请求头 (Headers)
所有请求需携带以下 Header：
| Header | 必填 | 说明 |
| :--- | :--- | :--- |
| `Content-Type` | 是 | `application/json` |
| `Authorization` | 是 | `Bearer {token}` (登录后获取，除登录接口外均必填) |
| `X-Request-Id` | 否 | 用于日志追踪的唯一 ID (UUID) |
### 2. 统一响应格式
所有接口返回 JSON 数据，结构统一如下：
```json
{
  "code": 200,
  "message": "success",
  "data": {
    // 实际业务数据
  }
}

字段	类型	说明
code	int	业务状态码。200 为成功，40001 为参数错误，40002 为未登录，50000 为服务器内部错误
message	string	提示信息
data	object/array/null	返回数据负载

分页参数

列表接口通用分页参数（Query 参数）：

• page：页码，默认 1
• page_size：每页条数，默认 20，最大 100

接口详情模板（核心部分）

每一个接口按照下面的模板来写。

---
## 用户模块
### 1. 用户登录
**接口描述：** 通过用户名和密码获取 Token。
**请求方法：** `POST`  
**请求路径：** `/api/v1/auth/login`  
**请求参数 (Request Body - JSON)：**
| 参数名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `username` | string | 是 | 用户名，长度 5-20 位 |
| `password` | string | 是 | 密码，需 MD5 加密后传输 |
**请求示例：**
```json
{
  "username": "admin",
  "password": "e10adc3949ba59abbe56e057f20f883e"
}

响应示例 (成功 - HTTP 200)：

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 7200
  }
}

响应示例 (失败 - HTTP 200，业务错误)：

{
  "code": 40002,
  "message": "用户名或密码错误",
  "data": null
}

业务异常情况：

业务 code	说明
40002	用户名或密码错误
40003	账号已被禁用

---

**小技巧：** 若接口较多，建议给每个功能模块加一个二级标题（如 `## 用户模块`），并在文档开头添加目录（TOC）链接。
---
### 方案二：重型级—— OpenAPI (Swagger) 规范（适合大型项目、前后端分离、微服务）
这种方式**自动化程度高**，代码即文档，PHP 常用的工具有：
-   **zircote/swagger-php**：通过注解（Attributes）自动生成 OpenAPI 文档。
-   **L5-Swagger**：Laravel 框架首选的包。
#### 1. 安装与集成（以 Laravel + L5-Swagger 为例）
```bash
composer require darkaonline/l5-swagger

在 Controller 中添加注解

直接在 PHP 代码中写接口文档，保证文档与代码同步更新。

<?php
namespace App\Http\Controllers\Api;
use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
class AuthController extends Controller
{
    /**
     * @OA\Post(
     *      path="/api/v1/auth/login",
     *      summary="用户登录",
     *      description="通过用户名和密码获取 Token",
     *      tags={"用户认证"},
     *      @OA\RequestBody(
     *          required=true,
     *          @OA\JsonContent(
     *              required={"username","password"},
     *              @OA\Property(property="username", type="string", example="admin", description="用户名"),
     *              @OA\Property(property="password", type="string", example="e10adc...", description="MD5密码")
     *          )
     *      ),
     *      @OA\Response(
     *          response=200,
     *          description="登录成功",
     *          @OA\JsonContent(
     *              @OA\Property(property="code", type="integer", example=200),
     *              @OA\Property(property="message", type="string", example="登录成功"),
     *              @OA\Property(property="data", type="object",
     *                  @OA\Property(property="token", type="string", example="eyJhb..."),
     *                  @OA\Property(property="expires_in", type="integer", example=7200)
     *              )
     *          )
     *      ),
     *      @OA\Response(response=401, description="用户名或密码错误")
     * )
     */
    public function login(Request $request)
    {
        // ... 业务逻辑
        return response()->json([
            'code' => 200,
            'message' => '登录成功',
            'data' => [/* ... */]
        ]);
    }
}

访问文档

启动服务后,访问 /api/documentation，即可看到 Swagger UI 交互式文档，支持“Try it out”直接调试。

---

辅助工具类（实用派）

如果不想手动写太多字,可以使用以下工具生成：

1. Postman：
   • 在 Postman 中调试好接口后，生成“公用链接”或分享到工作空间，团队实时查看。
   • 优点：方便调试；缺点：不随代码版本管理，容易文档与代码不同步。
2. Apifox / Apipost：
   • 国内协作利器,可以后置脚本自动同步数据库表结构，或者导入 Postman 数据，建议导出 Markdown 格式，放在 Git 仓库中作为备份。

---

高级建议（避坑指南）

1. 必须定义“业务错误码”：不要只依赖 HTTP 状态码，因为 PHP 项目（如 Laravel）通常异常时会返回 200 OK，但 data 里包含业务错误，定义好 code 和 message 字典是必须的。
2. 版本控制（Versioning）：接口 URL 中一定要带 v1（如 /api/v1/user），如果将来有破坏性变更（如修改字段名），建议新增 v2 接口，而不是直接修改 v1。
3. 字段命名规范：建议始终使用 snake_case（如 user_name）或始终使用 camelCase（如 userName），PHP 通常偏好 snake_case，但若前端是 JS，camelCase 更受欢迎，二选一，并在文档中明确注明。
4. 补充“时序图”：对于复杂的业务（如支付、OAuth2.0 授权），用一张时序图（Mermaid 支持 Markdown 中绘制）远比文字描述清楚。

sequenceDiagram
    participant 前端
    participant 后端
    participant 数据库
    前端->>后端: 提交登录信息
    后端->>数据库: 查询用户
    数据库-->>后端: 返回用户信息
    后端-->>前端: 返回 Token

总结建议：

• 优先级：如果项目是 Laravel/Symfony，推荐使用 Swagger 注解，这是最专业的 PHP 做法。
• 如果赶时间：直接用 Markdown 写，但确保每个 Controller 的方法体前都有清晰的 注释，方便后续生成。
• 最核心的一点：代码改了，记得同步改文档！ 没有这一点，写再多规范都没用。