【免费下载链接】blumeThe open-source docs framework for humans and agents.项目地址https://gitcode.com/gh_mirrors/blum/blume点击查看免费下载Blume是一个开源的文档框架支持人类读者和 AI 智能体。它的最大亮点之一是把OpenAPI、AsyncAPI 和 GraphQL 三大 API 规范一键生成 API 参考页每行配置指向你的规范文件JSON 或 YAML 均可构建后每个接口就是一个带独立 URL 的真实页面自带侧边栏分组、参数表格、多语言代码示例和交互式Try it 试用面板还会自动进入站内搜索、llms.txt和 Open Graph 分享图。如果你已经写过规范哪怕只是框架自动导出的那一份不用再手写几十页 API 文档——本文带你快速上手。三种规范一个统一入口Blume 把参考页抽象为三种适配器adapter统一从 blume/reference 导出在blume.config.ts的reference列表中声明openapi()—— REST APIOpenAPI / Swagger 规范asyncapi()—— 事件驱动 APIKafka、WebSocket、MQTT 等graphql()—— GraphQL 模式SDL 文本或内省 JSON三种适配器共享同一套原生渲染器配置项也基本互通route、codeSamples、expandSchemas等。参考文档位于 apps/docs/content/docs/references/openapi.mdx、apps/docs/content/docs/references/asyncapi.mdx 和 apps/docs/content/docs/references/graphql.mdx。最快配置方法三行接入 OpenAPI在blume.config.ts中导入openapi把规范文件放在项目根目录再让导航指向/referenceimport { defineConfig } from blume; import { openapi } from blume/reference; export default defineConfig({ reference: [openapi({ spec: ./openapi.yaml })], navigation: { tabs: [{ label: API, path: /reference }] }, });完成。规范支持三种来源与版本本地文件相对路径构建时读取JSON/YAML 均可blume dev会监听文件热更新或https URLSwagger 2.0 和 OpenAPI 3.0 会自动升级解析为 3.13.1、3.2 按原样渲染挂载位置可用route自定义如route: /api后总览页在/api每个操作页在/api/标签/操作AsyncAPI给事件驱动 API 生成参考页如果你的 API 是 Kafka、WebSocket、MQTT 这类发事件的接口用asyncapi()适配器。每个send/receive操作都会生成一个真实页面包含消息 payload 与 header 的 schema 表格频道参数、协议绑定、从securitySchemes推导的授权说明协议感知的代码示例WebSocket 生成wscat和浏览器片段Kafka 生成kcat自动带上 SASL/TLS 参数MQTT 生成mosquitto_pub/sub事件 Try it 面板WebSocket 可真实连接、逐帧打印日志其他协议提供可复制的 CLI 示例AsyncAPI 2.x 规范会通过官方转换器自动规范化为 3.x旧的publish/subscribe频道稳定映射到send/receive页面。相关源码见 packages/blume/src/openapi/asyncapi.ts。GraphQL每个字段和类型都有独立页面graphql()接受.graphql的 SDL 文本或内省查询的 JSON 结果为每个根字段query / mutation / subscription和每个命名类型对象、枚举、接口、联合、自定义标量各生成一页内容包括参数、默认值、deprecated标记、Used by 反向引用按模式类型自动生成的完整示例操作 示例变量 对应响应指向endpoint你的 GraphQL API 地址的 Try it 面板和多语言请求示例核心实现位于 packages/blume/src/openapi/graphql.ts 与 packages/blume/src/reference/graphql.ts。常用进阶能力一览能力说明多规范发布sources列表可挂多个规范各自独立路由与侧边栏分组适合多服务 API 门户Overlay 覆盖层规范由工具生成或别的团队维护时用独立 YAML 文件改写描述、删掉内部接口文档改动不侵入原规范自选代码示例codeSamples支持 curl、Python、JS、Node、Go、Java、C#、Rust、Kotlin 等十余种语言默认 curl / js / pythonSDK 示例在规范中用x-codeSamples写你自己的 SDK 调用会排在生成示例之前Webhooks 与回调规范顶层webhooks每个都生成独立页面标注这是 API 主动发出的请求授权说明从规范的security自动渲染 Authorization 区块Bearer、API Key、Basic、OAuth2多方案按或分组AI 友好每个操作页自动提供 Markdown 版本URL 加.mdx进llms.txt、MCP 服务器和 AI 助手没有规范手写 API 页也能生成完整参考不是每个接口都有 OpenAPI 文件。在 MDX 页面加一行api: POST /users的 frontmatter用ParamField/ResponseField组件描述字段Blume 就会像渲染规范页面一样自动生成方法路径、Try it 面板和 curl/JS/Python 请求示例。详见 apps/docs/content/docs/references/api-pages.mdx。没有规范时的替代嵌入 Scalar如果只是想快速展示一份规范而不需要 Blume 原生页面scalar()适配器可以把 Scalar 的自包含参考 UI 内嵌到单个路由自带侧边栏、搜索、主题和请求客户端。动手试试完整的示例配置仓库内的 sandbox 项目演示了三种适配器同时启用的完整配置含 Overlay、多 source、GraphQL 端点配置文件apps/sandbox/blume.config.ts示例规范apps/sandbox/specs/openapi.yaml、apps/sandbox/specs/asyncapi.yaml、apps/sandbox/specs/schema.graphqlOverlay 示例apps/sandbox/specs/public.overlay.yaml配合官方指南一步步走通从规范到上线的完整流程apps/docs/pages/guides/openapi-documentation-website.astro多规范组合成一个 API 门户apps/docs/pages/guides/multiple-openapi-specs-documentation.astro用 Overlay 从公开文档中移除内部接口apps/docs/pages/guides/openapi-overlays-public-docs.astro规范与后端在 CI 中保持同步apps/docs/pages/guides/openapi-documentation-ci.astro小结你的场景推荐做法有 OpenAPI/Swagger 文件openapi()适配器三行配置接入Kafka / WebSocket / MQTT 事件 APIasyncapi()适配器协议感知示例 事件 composerGraphQL 服务graphql()适配器字段和类型各成页规范由工具生成、别人维护叠加 Overlay公开文档自动裁剪内部接口个别接口没有规范手写apifrontmatter 页面照样拿到 Try it 面板规范写好了文档这一半就交给 Blume 自动完成吧 赞分享【免费下载链接】blumeThe open-source docs framework for humans and agents.项目地址https://gitcode.com/gh_mirrors/blum/blume点击查看免费下载相关推荐Supabase 文档 spec 流水线从 OpenAPI 与 TypeDoc 规格文件生成 API 参考文档Supabase 文档 spec 流水线从 OpenAPI 与 TypeDoc 规格文件生成 API 参考文档 Supabase 文档站 apps/docs后端前端数据库Umi-OCR离线OCR完整指南批量图片识别教程Umi OCR离线OCR完整指南批量图片识别教程 周五下午四点桌上堆着 40 页 A3 扫描件下班前要把它们转成能全文检索的文本顺手还有一张 2 万像素OCR桌面应用如何利用OpenAPI规范打造智能API参考GitBook自动化文档完整指南如何利用OpenAPI规范打造智能API参考GitBook自动化文档完整指南 GitBook API文档自动化是现代API开发的重要环节它利用OpenAPI前端后端知识管理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考