接口文档要用于正式发布，必须满足一系列严格条件——结构清晰分明、字段定义完整、示例数据真实、格式统一样式一致，并且能够脱离开发环境独立运行。简而言之，它必须基于结构化数据源（例如 openapi.yaml）来生成，再通过 Trae CLI 注入版本号、变更标记等元数据，最终导出为 HTML、OpenAPI JSON 或带水印的 PDF。完成这三步关键操作，文档才真正具备“可交付”的资质。

换句话说，你交付的不应只是一份本地调试的草稿，而是一份能够直接提供给前端、测试团队甚至客户查阅的正式版本。那么，如何从零散的输出内容转变为这种“终版成品”？核心就在于以下三个关键步骤。

确认文档源是否已结构化

先问一个基础问题：你当前的文档是从哪里来的？是从代码注释自动抽取生成的，还是基于 OpenAPI YAML/JSON 规范编写的，或者是通过 Apifox 这类平台同步而来的？如果文档只是 AI 零散输出的纯文本内容，那么很遗憾——必须先退回上一步，补全元数据后再继续推进。否则后续所有格式化操作都会遇到问题：参数类型丢失、必填标识缺失、状态码信息混乱不清，根本无法正常使用。

如何检查？打开 docs/api/ 目录，确认是否存在 openapi.yaml 或 openapi.json 文件。如果只有 README.md 这类说明文档，说明尚未触发 Trae 的结构化提取流程——请先补充这一步再继续操作。

用Trae CLI注入发布级元数据

这一步决定了文档是否具备“可发布”的核心属性。不仅仅是添加一个标题那么简单，而是要让每个接口都携带版本号、变更标记以及兼容性说明。这才是专业文档应有的标准。

在项目根目录执行以下命令：
trae docs inject --version 1.3.0 --since v1.2.0 --compatibility breaking

这条命令会扫描 Git 提交范围，自动为新增或修改的接口添加 deprecated: false、x-trae-changed: true 这类扩展字段，同时在文档顶部写入语义化版本头。这里有一个容易忽略的细节：如果不加 --since 参数，全部接口都会被标记为“首次发布”，真实的变更范围就被完全掩盖了——这相当于让版本管理失去了意义。

导出为多端就绪格式

根据不同的交付场景，有三种导出方式可供选择，分别对应不同的使用需求。

方法一：生成静态HTML站点（适合内部交付与离线查阅）
运行 trae docs build --format html --output dist/docs。生成的 index.html 自带搜索功能、侧边导航和响应式布局，无需搭建服务器即可直接双击打开。团队内部传阅、离线审阅都非常方便。

方法二：导出为Apifox/Yapi可导入的JSON（适合协同平台对接）
执行 trae docs export --format openapi3-json --strict --output docs/api/openapi-v1.3.0.json。请注意这里的 --strict 必须启用——它会逐一校验所有 $ref 引用是否有效、所有 response schema 是否可解析。只要有一项校验失败，导出就会立即中断，确保不会把一张有问题的 schema 上传到平台，从而避免收到“schema invalid”的报错提示。

方法三：生成带水印的PDF（适合客户签约交付）
先确认系统已安装 wkhtmltopdf，然后执行以下命令：
trae docs pdf --source dist/docs/index.html --watermark "CONFIDENTIAL - v1.3.0" --output deliverables/api-docs-v1.3.0.pdf

水印内容支持自定义，版本号、保密级别等信息都可以写入。在向客户交付时，这个 PDF 就是最正式、最规范的交付物。