BlueDoc GraphQL API参考：文档、评论与目录接口完全说明

BlueDoc GraphQL API参考文档、评论与目录接口完全说明【免费下载链接】bluedocAn open-source document management tool for enterprise self host.项目地址: https://gitcode.com/gh_mirrors/bl/bluedocBlueDoc 是一款面向企业的开源自托管文档管理工具内置完整的 GraphQL API让你可以用一条接口同时操作文档、评论与目录TOC非常适合做二次开发或对接自研系统。本文是一份完整的 BlueDoc GraphQL API 参考覆盖查询Query与变更Mutation两大类接口、核心数据类型的字段说明以及可直接套用的请求示例看完即可上手调用。 快速开始发送第一个 GraphQL 请求BlueDoc 的 GraphQL 入口由 GraphQLControllerapp/controllers/graphql_controller.rb提供采用标准的 GraphQL 调用方式请求方式POST到服务的 GraphQL 端点请求体JSON包含query查询语句、variables变量支持 JSON 字符串或对象、operationName认证方式基于会话的登录态Devise登录后调用即可权限校验由 CanCanCan 自动完成默认分页分页接口默认每页 50 条见app/graphql/bluedoc_schema.rb最简请求示例——先用测试接口hello验证连通性query { hello }登录后调用会返回带用户名问候的内容是验证会话与接口是否打通的最佳方式。 文档与目录查询接口Query查询类型定义在app/graphql/queries/目录下各 Query 按职责拆分到不同文件核心能力如下获取单篇文档doc(id)按 ID 精确获取一篇文档返回Doc类型常用字段包括字段说明slug文档唯一标识path文档完整路径title文档标题bodyMarkdown 正文body_smlSML 格式正文主要内容载体body_html渲染后的 HTML 结果last_editor最后编辑人User 类型toc文档对应的目录节点query { doc(id: 101) { slug title path body last_editor { name } } }获取知识库目录树repository_tocs(repositoryId)一次性拿到整个知识库Repository的目录列表自动按目录树顺序toc order返回若知识库未启用目录则按文档创建顺序返回是渲染侧边栏导航的首选接口。分页获取知识库文档repositoryDocs支持分页与排序适合做文档列表页repositoryId必填知识库 IDpage页码默认 1per每页条数默认 20sort排序方式created按创建顺序或最近更新全局搜索search(type, query)search接口支持按类型搜索type可取user、group、repository、doc搜索文档时可传repositoryId限定在指定知识库内此时允许命中私有文档limit控制结果数量默认 10。搜索结果包含总数total与记录集records底层由lib/bluedoc/search.rb的搜索组件驱动。 评论与行内评论接口评论相关接口在app/graphql/queries/comments_query.rb与inline_comments_query.rb中实现支持两种评论形态普通评论comment(id)按 ID 获取单条评论返回Comment类型comments(...)分页获取某对象下的全部评论参数如下参数说明commentableType被评论对象类型如DoccommentableId被评论对象主键nid行内评论锚点 ID可选page/per分页参数默认第 1 页、每页 20 条Comment类型字段包含bodyMarkdown 内容、body_sml、body_html、user评论人、parent_id与reply_to父评论天然支持楼中楼并内置表情回应Reaction能力。 获取评论列表的同时接口会自动把当前用户对应的通知标记为已读无需额外调用。行内评论InlineCommentinline_comments(subjectType, subjectId)获取文档下所有带回复的行内评论当前支持Docinline_comment(id)按 ID 获取单条行内评论行内评论通过nid锚点绑定到文档中的具体选区是做划词评论功能的核心。✏️ 变更接口Mutation速查表所有 Mutation 集中注册在app/graphql/types/mutation.rb按功能分为四组 文档操作接口说明关键参数createDoc在知识库中创建新文档repositoryId必填、slug可选deleteDoc删除文档文档 ID 目录操作接口说明关键参数createToc创建目录节点repositoryId、title、external是否仅创建外链节点、targetIdposition插入位置left/right/childmoveToc移动目录节点实现排序/缩进id、targetId、positionupdateToc更新目录节点节点 ID 与更新字段deleteToc删除目录节点节点 IDcreateToc很灵活external为false时会同时创建一篇空文档并挂到目录树上为true时仅创建外链目录项二者都能通过targetIdposition精确控制插入位置适合自动批量生成文档结构。 评论与表情操作接口说明关键参数createComment发表评论commentableType、commentableId、body、body_sml、parentId回复时、nid行内评论时createInlineComment发表行内评论锚点与内容参数updateComment修改评论评论 ID 与新内容deleteComment删除评论评论 IDwatchComments关注/取消关注评论评论对象updateReaction设置或取消表情回应目标对象与表情发表评论的完整示例mutation { createComment( commentableType: Doc commentableId: 101 body: 这段内容建议补充示例 body_sml: 这段内容建议补充示例 ) { id body user { name } } } 核心返回类型一览类型定义位于app/graphql/types/目录Docdoc_type.rb文档主体含多格式正文与目录节点Comment / Commentscomment_type.rb单条评论与分页评论集合集合类型records返回当前页数据Toctoc_type.rb目录节点含parent_id、depth层级深度、title、url、doc_id用depth即可在前端还原树形结构PageInfopage_info_type.rb统一分页信息所有分页接口均附带方便前端做翻页Useruser_type.rb用户基础信息评论人、最后编辑人等字段均引用该类型 权限与错误处理每个接口内部都通过authorize!做细粒度权限校验CanCanCan无权限时会返回CanCan::AccessDenied的错误消息记录不存在时统一返回Record not found开发环境下出错会返回详细堆栈生产环境只暴露错误消息方便排查又不泄露内部信息 小结BlueDoc 的 GraphQL API 用一套统一入口覆盖了文档管理、目录编排、评论互动三大场景查询侧提供doc、repositoryDocs、comments、search等读取接口变更侧提供createDoc、createToc、moveToc、createComment等写入接口配合统一的分页与权限体系足以支撑完整的文档协作平台二次开发。建议先用hello接口验证连通性再按查文档 → 拉目录 → 读写评论的顺序逐步接入。【免费下载链接】bluedocAn open-source document management tool for enterprise self host.项目地址: https://gitcode.com/gh_mirrors/bl/bluedoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考