修炼AI技能
AI 教程 / AI 编程实战 / AI 生成技术文档与 API 文档：从代码到可读文档

AI 生成技术文档与 API 文档：从代码到可读文档

写文档是开发者最常说「等我有空再做」的事。代码改了，文档没动；接口上线了，说明还停在草稿。大模型的强项是把意图和上下文转成连贯文字，这恰好补上了文档工作里最耗神的部分。本文讲清 AI 在文档场景能做什么、有哪几种生成范式、怎么实操，以及最危险的一个陷阱：模型会编造并不存在的 API。

AI 在文档场景的价值

文档不是一种东西，而是一组形态各异的产物。AI 在其中各有用武之地：

  • 函数注释（docstring）。给一段已实现的函数，让模型补出参数说明、返回值、异常与示例，让 IDE 悬浮提示更实用。
  • README。从仓库结构、入口文件和测试方法自动起草项目说明，降低新成员的上手成本。
  • API 参考。把 OpenAPI/Swagger 这类机器契约，转成人类能读的端点说明、请求示例与错误码表。
  • 变更日志（changelog）。对比两次提交或版本标签，归纳「新增、修复、变更、废弃」，生成符合规范的更新记录。

注意一个边界：模型产出的是「草稿」而非「事实」。它不知道你没告诉它的约束，也可能把相似库的接口张冠李戴。后面会专门讲校验。

文档生成范式

注释驱动：AI 读代码补 docstring

最常见、风险最低的一类。你把函数本体贴给模型，要求按某种规范（如 Google、NumPy、reStructuredText）补 docstring。模型依据代码里的变量名、控制流、返回语句推断语义，准确性相对高，因为信息就在眼前。

适用场景：给存量项目补齐注释、统一注释风格、为已有函数生成类型与异常说明。

用 LLM 把 OpenAPI/Swagger 转人类文档

OpenAPI 文档对机器友好，对人却像读规格书。把 spec 交给模型，可生成：每个端点的通俗用途、带真实字段的 curl/Python 请求示例、鉴权方式、常见错误码与排查建议。这一步把「契约」翻译成「指南」，是 API 文档站最常受益的环节。

代码加示例生成教程

给模型一段可运行代码和几个真实输入输出，它能写出带步骤、带代码片段、带预期结果的教学短文。比纯注释更上一层：不仅说明「是什么」，还说明「怎么用、为什么这样用」。

三种范式由浅入深，风险也依次升高——离真实代码越远（从函数到端点再到叙事教程），模型自由发挥的空间越大，越需要你事后核对。

实操：给一段 Python，用 AI 生成 docstring 与 README 片段

下面是一段没有注释的 Python 函数。我们让它补全文档。

原始代码：

def retry_fetch(url, max_retries=3, backoff=0.5):
    import time
    import requests

    last_err = None
    for attempt in range(max_retries):
        try:
            resp = requests.get(url, timeout=5)
            resp.raise_for_status()
            return resp.json()
        except requests.RequestException as err:
            last_err = err
            time.sleep(backoff * (attempt + 1))
    raise RuntimeError(f"请求失败，已重试 {max_retries} 次: {last_err}")

交给模型的提示（注意带语言标识、给出规范要求）：

请为下面的 Python 函数补全 Google 风格 docstring，包含功能简述、参数、返回、异常与一条使用示例。只输出函数代码与 docstring，不要额外解释。

<粘贴上面的函数>

模型可能返回：

def retry_fetch(url, max_retries=3, backoff=0.5):
    """带退避重试地拉取 JSON 接口。

    Args:
        url: 目标地址，需返回 JSON。
        max_retries: 最大重试次数，默认 3。
        backoff: 退避基数（秒），第 n 次重试等待 backoff * n。

    Returns:
        解析后的 JSON 对象（dict 或 list）。

    Raises:
        RuntimeError: 所有重试均失败后抛出，并附带最后一次错误。

    Examples:
        >>> data = retry_fetch("https://api.example.com/health")
        >>> data["status"]
        'ok'
    """
    import time
    import requests

    last_err = None
    for attempt in range(max_retries):
        try:
            resp = requests.get(url, timeout=5)
            resp.raise_for_status()
            return resp.json()
        except requests.RequestException as err:
            last_err = err
            time.sleep(backoff * (attempt + 1))
    raise RuntimeError(f"请求失败，已重试 {max_retries} 次: {last_err}")

同一个函数，再让模型起草一段 README 片段：

基于上面的 retry_fetch 函数，写一段 README 片段，含「安装依赖」「用法示例」「重试策略说明」三小节，使用 Markdown。

它会产出带标题、代码块和要点列表的短文档。这里要核对两点：示例里的 data["status"] 是否真的存在于你的接口返回里（模型可能假设字段），以及「安装依赖」里写的 requests 是否确实在 requirements 中。

工具

下面按公开定位介绍，具体能力请以官方最新文档为准，本文标「待核实」之处请二次确认。

  • Swimm。官方定位为「Agentic modernization」平台，用静态分析加生成式 AI 加资深工程师，把代码转成可追踪、结构化的系统理解，覆盖依赖图、关键流程文档，并强调「随代码演进而保持更新」（Stays current）。其公开材料还专门指出「AI 单独使用会幻觉」，因此用确定性分析锚定输出。它直接对应本文两个主题：文档与代码同步、以及对抗幻觉。定位已核验，具体功能待核实。
  • Mintlify。定位为「面向 Agent 的知识平台」，主打 self-updating documentation（自更新文档）与 AI-native 文档站，广泛用于开发者文档。适合把 API 参考与指南做成可维护的网站。定位已核验，具体功能待核实。
  • Stoplight。定位为 API 设计优先（design-first）平台，提供 OpenAPI/Swagger 的设计、文档与全生命周期管理，强调用 OAS 标准与可复用组件产出高质量 API。它是把 spec 转成文档站的成熟选择。定位已核验，具体功能待核实。
  • Documatic。该域名当前已跳转至 Rover（代码可靠平台，含 PR 扫描与 AI 代码探索），其早期「AI 文档生成与代码搜索」定位是否仍独立存在，本文标为待核实，请以其官方现状为准。
  • 各 IDE 的 AI 文档能力。GitHub Copilot Chat、Cursor、Claude Code 等可在编辑器内基于当前文件生成 docstring、解释函数、起草说明，属于「注释驱动」范式最顺手的入口，具体命令与可用性待核实。

陷阱：AI 会编造不存在的 API

这是本文最重要的一节。模型按照「最可能的写法」补全，而不是按照「你代码里真实存在的符号」。它会：

  • 编造参数名。函数实际叫 timeout，它写成 read_timeout；实际没有 verify 参数，它加上了。
  • 编造整支 API。文档里出现你们根本没实现的端点，或把别的库的接口安到你的项目上。社区称之为 hallucinated API（幻觉 API）。
  • 假设返回字段。上面示例里的 data["status"]，若你的接口并不返回该字段，读者照抄就会 KeyError。
  • 过时的用法。模型可能用已被弃用或尚未发布的库版本写法。

应对办法只有一条：文档必须对照真实代码校验。具体可做：

  • 生成 docstring 后，用类型检查器与 doctest 跑一遍示例，确认示例真的能运行。
  • API 参考里的每个端点、参数、错误码，逐一对照 OpenAPI spec 或路由定义，不要只看模型摘要。
  • 把文档纳入评审。文档改动和代码改动走同一个 PR，让 reviewer 像看代码一样看文档。
  • 让文档随代码更新。Swimm 这类工具的价值正是「系统理解随代码演进而更新」；即便不用工具，也应在 CI 里对关键接口做文档与契约的一致性检查，避免文档漂移。

记住：AI 生成的是高完成度的草稿，不是已盖章的事实。你才是真实代码的权威来源。

小结

AI 在文档场景的价值覆盖函数注释、README、API 参考与变更日志四类产物。三种范式由浅入深：注释驱动最稳，把 OpenAPI 转人类文档次之，代码加示例生成教程最考验校验。实操上，给模型带语言标识的代码与明确规范，即可快速产出 docstring 与 README 片段。但最大风险是模型会编造不存在的 API 与参数，因此文档必须对照真实代码校验、随代码更新，并纳入同一套评审与 CI 流程。Swimm、Mintlify、Stoplight 等工具分别覆盖「文档随代码同步」「AI-native 文档站」「OpenAPI 设计优先文档」，具体能力请以官方最新资料为准。

参考与延伸阅读

  • Swimm 官方站点（产品定位：代码理解、文档随代码更新、对抗幻觉） https://swimm.io （定位已核验，具体功能待核实）
  • Mintlify 官方站点（产品定位：面向 Agent 的自更新文档平台） https://mintlify.com （定位已核验，具体功能待核实）
  • Stoplight 官方站点（产品定位：OpenAPI/Swagger 设计优先与文档管理） https://stoplight.io （定位已核验，具体功能待核实）
  • Documatic 原站点（当前跳转至 Rover，早期 AI 文档/代码搜索定位待核实） https://documatic.com （现状待核实）
  • Google Python Style Guide：docstring 规范参考 https://google.github.io/styleguide/pyguide.html （规范参考，已核验）
  • OpenAPI Specification 官方文档（把 spec 转为可读文档的契约基础） https://spec.openapis.org/oas/latest （规范参考，已核验）
本文累计阅读 — 次