Redoc中jsonSampleExpandLevel参数的正确使用方式

在使用Redoc进行API文档渲染时，开发者经常需要控制JSON示例的展开层级以提升文档可读性。本文详细介绍jsonSampleExpandLevel参数的正确配置方法。

常见配置误区

许多开发者会误将jsonSampleExpandLevel参数放在theme配置对象中，例如：

<redoc spec-url='./api.json'
  theme='{
    "openapi": {
      "jsonSampleExpandLevel": "all"
    }
  }'>
</redoc>

这种写法实际上不会生效，因为jsonSampleExpandLevel并非theme的子属性。

正确配置方式

jsonSampleExpandLevel应作为Redoc标签的直接属性使用，支持以下两种等效写法：

1. 驼峰式写法（推荐）：

<redoc spec-url='./api.json' jsonSampleExpandLevel="all"></redoc>

2. 短横线分隔式写法：

<redoc spec-url='./api.json' json-Sample-Expand-Level="all"></redoc>

参数取值说明

该参数支持三种取值：

• "all"：展开所有层级
• 数字（如2）：展开到指定层级
• 不设置：使用默认展开层级

实际效果对比

当设置为"all"时，文档中所有JSON示例都会完全展开，方便开发者查看完整的请求/响应结构。而使用数字时（如2），则只会展开到第二层嵌套，更深层的内容会保持折叠状态。

最佳实践建议

1. 对于结构简单的API，建议使用"all"完全展开
2. 对于复杂API文档，建议使用数字控制展开层级（通常2-3层为宜）
3. 在开发调试阶段可以使用完全展开，生产环境根据文档复杂度调整

通过正确配置这个参数，可以显著提升API文档的可用性和用户体验。