跳到正文

编写第三方集成指南

交代两套工具之间的版本和数据约定,演示最小接入并提供端到端验证。

说明集成的边界

开头写清要连接的两个工具和完成后能看到的结果。例如,“把构建器生成的 JSON 索引交给静态站搜索页面,使读者可以按标题找到文档”。列出已准备的仓库、支持的版本和实际验证环境。

用行内链接引导读者完成各自产品的安装与账号配置,再解释两者如何衔接。第三方功能、套餐、权限和界面以它的官方文档为准。界面使用英文名称时,在操作步骤中写出实际控件名,必要时补一句中文说明。

写清每一方负责什么

负责方读者要配置的内容验证依据
索引生成器生成含条目标识和标题的 JSON构建目录中的输出文件
静态站在公开资产路径提供索引该路径响应成功,内容为 JSON
搜索页面读取路径,用标题匹配查询输入示例标题得到对应结果

注明配置文件、变量名与环境。使用环境变量时说明它由哪一方读取、什么时候加载。示例凭据使用占位符,要求在服务端使用的值放在对应的服务端配置步骤。

验证整个往返路径

用可识别的样例输入,例如只收录一篇名为“配置搜索”的页面。生成索引后先检查文件,再打开预览页搜索这个完整标题。结果为空时,从输出路径、部署产物、已发布的索引版本依次检查。

发布后记录已验证的工具组合和对应版本。任一侧更新时先验证最小示例,再更新故障排查中与这次变化相关的条件。