第 6.4 章：API 文档化

学习时间： 30 分钟

1. 为什么需要 API 文档？

想象一下，你拿到一个复杂宇宙飞船的控制台，上面没有任何按钮的标签。你会随意按下它们，冒着启动弹射而非打开灯光的风险。API 文档正是那些标签和说明。

好的文档：

节省时间： 开发者无需猜测存在哪些端点、它们接受什么参数以及返回什么。
减少错误： 清晰的数据格式和错误代码描述有助于避免不正确地使用 API。
简化集成： 前端团队可以与后端团队并行工作，将文档作为契约。
是你的遗产： 半年后当你回到项目时，你会感谢自己。

💡 宇宙类比：

API = 复杂的空间站管理系统。

API 文档 = 宇航员手册。其中描述了：

发送什么命令（端点）来打开气闸。

传递什么参数（请求体）来配置生命维持系统。

期望收到什么信号（API 响应）作为回应。

2. FastAPI 中的文档：自动化魔法

FastAPI 让文档化变得异常简单。它利用 OpenAPI 和 Swagger UI 标准，根据你的代码自动生成交互式文档。

步骤 1：在你的应用中添加元数据

在 main.py 中可以添加将出现在文档中的描述。

# main.py
from fastapi import FastAPI
from pydantic import BaseModel, Field

# ... (FastAPI 代码)

app = FastAPI(
    title="SpaceAPI",
    description="""
探索银河系的 API。🚀

你将能够：
* **查看行星**。
* **添加新世界**（需要身份验证）。
    """,
    version="1.0.0",
    contact={
        "name": "控制中心总工程师",
        "url": "https://example.com/contact",
        "email": "engineer@example.com",
    },
)

步骤 2：描述你的模型和端点

你对 Pydantic 模型和端点参数的描述越详细，文档就越好。

# 在 Pydantic 模型文件或 main.py 中

class PlanetBase(BaseModel):
    name: str = Field(..., example="地球", description="行星名称")
    description: str = Field(..., example="一颗拥有多样生命的蓝色星球", description="简短描述")
    # ...

class Planet(PlanetBase):
    id: int
    is_habitable: bool

    class Config:
        orm_mode = True # 或 Pydantic v2 中的 from_attributes = True

# 在路由文件中
@router.get(
    "/planets",
    response_model=list[Planet],
    summary="获取所有行星列表",
    description="返回所有已知行星的列表，（未来）带分页。"
)
def get_planets():
    # ...

@router.post(
    "/planets",
    # ...
    summary="创建新行星",
    responses={
        401: {"description": "用户未授权"},
        422: {"description": "数据验证错误"}
    }
)
def create_planet(planet: PlanetCreate, ...):
    # ...

Field(..., example="..."): 在文档中添加示例。
summary: 端点的简要描述。
description: 详细描述。
responses: 描述除成功响应外的可能状态码。

步骤 3：在浏览器中打开文档

启动你的 FastAPI 服务器并打开两个神奇的 URL：

http://127.0.0.1:8000/docs — 将打开交互式 Swagger UI 文档。你不仅可以在这里阅读，还可以直接从浏览器中测试你的端点！
http://127.0.0.1:8000/redoc — 将打开另一种文档视图 ReDoc。它交互性较差，但通常更具可读性。

3. Laravel 中的文档：使用第三方包

与 FastAPI 不同，Laravel 不会“开箱即用”地生成文档。然而，有一些优秀的包可以通过分析你的代码来完成这项工作。最受欢迎的是 Scribe。

步骤 1：安装 Scribe

composer require --dev "knuckleswtf/scribe"

php artisan vendor:publish --tag=scribe-config
php artisan scribe:generate

步骤 2：使用 DocBlocks 描述端点

Scribe 会读取你的控制器方法上方的 PHP DocBlocks（/** ... */ 形式的注释）。

打开 app/Http/Controllers/PlanetController.php:

// app/Http/Controllers/PlanetController.php

/**
 * @group 行星
 * 行星管理 API
 */
class PlanetController extends Controller
{
    /**
     * 获取行星列表
     *
     * 返回银河系中所有行星的分页列表。
     *
     * @unauthenticated
     */
    public function index()
    {
        // ...
    }

    /**
     * 创建新行星
     *
     * @authenticated
     *
     * @bodyParam name string required 行星名称。Example: Kepler-186f
     * @bodyParam description string required 行星描述。
     * @bodyParam size_km integer required 直径（公里）。Example: 14000
     * @bodyParam is_habitable boolean 行星是否宜居。Example: true
     *
     * @response 201 {
     *  "id": 4,
     *  "name": "Kepler-186f",
     *  "description": "第一颗在其他恒星宜居带中确认的地球大小行星。",
     *  "size_km": 14000,
     *  "is_habitable": true,
     *  "created_at": "2023-10-27T12:00:00.000000Z",
     *  "updated_at": "2023-10-27T12:00:00.000000Z"
     * }
     */
    public function store(Request $request)
    {
        // ...
    }
    // ... 其他方法以此类推
}

Scribe 关键标签：

@group: 对端点进行分组。
@unauthenticated / @authenticated: 指示是否需要令牌。
@bodyParam: 描述请求体中的参数。
@response: 成功响应的示例。

步骤 3：生成和查看文档

每次修改 DocBlocks 后，运行以下命令：

php artisan scribe:generate

Scribe 将创建包含你文档的静态 HTML 页面。在以下地址打开它：http://your-app-url/docs。

巩固测验

🚀 本章总结：

你已经创建了专业的文档，将你的 API 从“黑盒子”变成了清晰易用的工具。

✅ 理解了 API 文档化的关键重要性。
🪄 学会了如何在 FastAPI 中使用自动文档生成。
⚙️ 掌握了 Scribe 包在 Laravel 中进行 API 文档化的基础知识。
🛰️ 确信良好的文档是任何开发者的最佳帮手。

你的 API 现在不仅可以工作并受到保护，而且已完全准备好供团队其他成员使用。 剩下最后但最重要的一步——最终安全检查。

📌 检查：

对于 FastAPI：在浏览器中打开 /docs 并尝试直接从 Swagger UI 界面对行星列表执行 GET 请求。

对于 Laravel：执行 php artisan scribe:generate 并打开 /docs。确保端点已分组，并且 store 方法有参数描述。