RSpecApiDocumentation资源注释为何未在Raddocs HTML中显示？

我之前踩过一模一样的坑！明明在RSpecApiDocs里给User资源加了explanation，生成的JSON里字段也好好的，但Raddocs的HTML页面就是死活不显示这行注释。别慌，这基本是两个核心原因导致的，咱们一步步来解决：

1. 先确认JSON输出的正确性 #

首先检查你的index.json，确保explanation字段确实挂在对应的资源节点下，结构没有问题：

{
  "name": "User",
  "explanation": "a User resource, duh",
  "endpoints": [...]
}

如果这个字段存在，那问题肯定出在Raddocs的前端渲染逻辑上——它默认没把这个字段加入到展示模板里。

2. 自定义Raddocs模板来展示注释 #

Raddocs支持自定义模板，你需要找到它的资源详情页面模板（老版本一般是views/resources/show.html.erb，新版本如果是React实现的话就是对应的组件文件），然后添加一段渲染explanation的代码：

针对ERB模板的情况： #

<% if resource['explanation'].present? %>
  <div class="resource-description">
    <h3>资源说明</h3>
    <p><%= resource['explanation'] %></p>
  </div>
<% end %>

把这段代码放在资源名称或者端点列表的上方，就能看到注释内容了。

针对React版本的Raddocs： #

找到负责渲染资源头部的组件（比如ResourceHeader.js），在合适的位置加入：

{resource.explanation && (
  <div className="resource-explanation">
    <h3>Resource Explanation</h3>
    <p>{resource.explanation}</p>
  </div>
)}

3. 检查RSpecApiDocs的配置是否正确 #

有时候可能是RSpecApiDocs没把explanation写入JSON，去你的spec_helper.rb里确认配置：

RSpecApiDocumentation.configure do |config|
  config.format = :json
  # 确保这个选项是开启的，默认应该是true，但以防被手动禁用了
  config.include_explanation = true
end

4. 重启服务并清理缓存 #

最后别忘了重启你的Raddocs服务，顺便清理一下静态文件缓存——有时候旧模板会被缓存，导致修改不生效。

按这几步操作下来，你的资源注释应该就能正常显示在Raddocs页面里了！

内容的提问来源于stack exchange，提问作者MikeMarsian