SuperAPI AI 工具集

confluence-api-doc

编程与开发

查看项目

更新于 10-15 20:09

技能介绍

用途:把 api-doc-gen 生成的 docs/api/ 多文件 API 文档同步到 Confluence,做到一个端点文件对应一个 Confluence 页面,目录结构直接映射为 Confluence 页面树,无需按标题拆分。

主要能力:index.md 作为父页面(服务概览与通用错误);子目录作为域分组父页面;每个 .md 端点文件作为 API 页面,标题取文件中的 Method + Path,格式如 POST: /api/v1/consents,而非 H1。跳过 health/ 目录;更新时先取当前版本号再加一;写前可对比内容跳过无变化页面;结束后输出结果表。

使用方式:先确认文档目录(默认 docs/api/,需存在 index.md 和至少一个含 .md 的子目录)与父页面 URL,并从 URL 提取数字页面 ID。用 acli auth status 验证认证并解析 CONFLUENCE_URL 与 EMAIL;未安装时 brew install atlassian/tap/acli,未登录时 acli auth login。因 acli confluence page 目前仅支持 view,创建/更新页面改用 Confluence REST API 配合 curl。写前通过 echo $CONFLUENCE_API_TOKEN 取令牌,为空则向用户询问。执行分两轮:先创建或更新域分组页面,再创建或更新各端点页面,以保证父子层级正确。更新页面需携带递增的 version.number。

适用场景:已有 docs/api/ 多文件 API 文档、并希望按域分组维护成 Confluence 页面树的团队,适合批量初始化或后续增量同步。

限制:acli 暂不支持页面写入,必须使用 REST API 与令牌;页面标题匹配为精确匹配,歧义或无法匹配时需人工确认或手动提供页面 ID;health/ 不同步;HTTP 401 需检查令牌,404 需核对页面 ID,409 为版本冲突需重新取版本后重试。其他细节原资料未提供。