2026年社区主动规划了接口文档生成的功能，目的是向社区开发者提供完整的接口说明，便于查阅或按产品发布，同时为了降低文档的维护成本，以及文档和软件版本的一致性， 目标是做到基于接口定义自动生成文档。
关于redfish接口文档，有以下初步思路：
1、基于DMTF官方的工具和JSON schema生成redfish接口说明文档（word/pdf）；
2、文档结构参考DMTF的文档DSP0246（参考[https://www.dmtf.org/sites/default/files/standards/documents/DSP2046_2025.4.pdf]），以资源为粒度说明redfish接口，每个资源会包含属性、Action说明，以及支持的操作类型(GET/PATCH/POST/DELTE)和示例；
3、提供Hook或插件/配置文件定制能力，便于产品在发布文档时做补丁修改，如Oem标识符替换，资源/属性的增加补充说明（限于特定产品或版本）；
欢迎各位开发者反馈意见。
邀请各位开发者反馈关于社区redfish文档建设方案建议，包括但不限于文档内容、文档结构、发布形式，感谢各位的反馈。
@KunLun_wangqindong @liujie_11 @qiuhao @chengxiaoju @wangyazhou @zmcheng @huangliang @jiangchao419 @pengshuang @luohao211737 @arch @ChenMinjun
建议社区引入文档编辑、评审、发布能力，支持历史记录和导出、回滚能力，不同节点设置不同的管理人员，可以导入当前版本，在此基础上，支持有权限人员编辑文档，经过评审流程后，生成发布文档（doc、pdf格式）。
此方式的前提还是文档采用单独维护的方式，没有跟代码仓的接口定义关联起来，从流程上看还是要在完成设计、开发、验证之后，人工更新文档，并需要投入专人审核，我们期望的是能基于当前社区的接口定义模型文件，自动生成文档，避免因为需要人工操作带来的文档和实现不一致风险
接口文档有通用的OpenAPI 3.0 或者Swagger 2.0格式.
接口文档应该从代码自动生成, 维护一个文档始终存在和代码脱节的风险.
在AI时代, 可以
一般情况, 从rackmount(以及定制仓)自动生成openapi.yml (
如何"自动生成"呢? 应该把人工更新文档的人力, 投入到 “rackmout自动生成openapi格式的AI skills”. skill支持按接口维度去生成而不是全量生成,一个接口通了, 剩下的让AI重复执行就行.
最开始生成的文档一般接口正确, 参数约束和描述不一定正确, 需要使用AI结合已有的接口文档调整纠正.
调整后, 接口文档中旧有的接口经过多个AI和人力交叉审核正确, 新增的接口需要人工审核确保正确(新增接口一般不会太多)
这时, 你已经拥有了redfish_openapi.yml格式的接口, 具备可以导入任何postman apipost等软件形成数字资产固化下来, 或接入任何AI直接查询调用的能力.
接下来, 从redfish_openapi.yml格式的接口生成接口文档是简单而显然的, 可以用脚本确定性地做.
每个版本的代码, 都不用管原始是什么样的, 直接改, 不用做补丁之类的. 因为代码和文档一致了
代码-openapi-文档, 代码是第一输入, openapi包含全部的信息,用于人类和AI开发测试使用, 文档只是openapi信息的一个视图. 代码和文档天然一致.
当然, 文档上线前还是需要人工审核, 如果发现问题了, 不应该修改文档, 而应该修改自动生成文档的脚本(机制不支持或有bug), 或者配置该接口的开发(代码不能自描述),然后重新生成
细节在于,当前配置文件, 需要支持自描述字段, 也就是每个接口的描述, 属性描述, 以及部分实例, 应该在呈现.当前的json格式不支持注释,导致缺失了这部分信息, 还是需要人把脑子里的信息搬运到文档里, 造成散列式修改和不一致的风险, 同时造成AI缺少信息输入,无法准确传递这一块信息. 所以建议配置文件格式,
代码是人编写的，难免会有与规范不一致或冲突的问题。另外，对外接口要有中文、英文资料，自动生成难免会有些描述不准确的问题。
通过人工编辑可以一定程度上解决这些问题，通过审核机制也可以发现并拦截一些问题。
假设前提： 从0开始生成文档
基于当前已有资源：redfish需求的SIG帖子。
实现： AI 根据SIG帖子（标准），整理格式，自动生成redfish接口文档。
你这也是AI咨询的吧，有尝试过吗
这个和AI没关系, 是我的思考. 这个思路是很显然的, openapi和swagger的通用交换格式几乎是事实上的标准. 如果你尝试使用过postman或者尝试开发自动化工具的一定会涉及到的
你可以尝试下，或者说用gpt think，gemini，或者calude 问下这块看看。
现在Ai给开发者编写代码不是把代码塞给他，文档也不是直接塞给ai，占用大量token。现在cursor+codex或者微软的那个，现在编写代码应该是基于语法树解析的，所以不会占用大量token，要么是rag，要么是索引库，来收敛编写代码这块。但是文档这块用AI难以收敛，目前还是自动化会合适点
还需要把 规范性条款（DSP0266）和 数据模型规范（DSP0268）纳入生成/校验链路。还需要个验证工具，DMTF 提供的 Protocol/Service/Interop validator 能用来检查协议与 schema/profile 符合性。
https://redfishforum.com/thread/41/api-documentation?utm_sourc
社区也有人明确吐槽过：doc-generator 只生成 schema 文档，不包含 endpoints。doc-generator 负责 schema 文档；endpoint/paths 通常用 openapi.yaml 来提供。DMTF 的标准解决方式是：在 DSP8010 里提供一份 OpenAPI service document：
DMTF官方的校验工具在Q1就会引入，但是会有一部分涉及到兼容性问题，需要白名单管理。所以我们也不是完全照搬官方的doc-generator，会基于官方的做一些改造，生成符合开发者/产品发布需要的文档
这个思路挺赞的，还有一些可视化的api设计工具https://apifox.com/