ReDoc项目中JSON示例展开级别的配置问题解析

在使用ReDoc这一流行的API文档生成工具时，开发者可能会遇到JSON示例默认折叠的问题。本文将从技术角度分析这一现象的原因，并提供正确的配置方法。

问题现象

当开发者尝试通过HTML方式集成ReDoc时，经常会出现JSON示例内容默认被折叠的情况。即使按照官方文档尝试通过theme属性配置jsonSampleExpandLevel参数，仍然无法实现预期的展开效果。

原因分析

经过技术验证，发现问题的根源在于配置方式的错误理解。ReDoc提供了多种配置方式，但在HTML标签属性中使用时，需要注意：

1. 参数命名转换：JSON参数名需要转换为kebab-case格式（短横线连接）
2. 直接属性配置：某些参数可以直接作为标签属性设置，而不需要通过theme对象

正确配置方法

要实现JSON示例的完全展开，正确的HTML配置方式如下：

<redoc spec-url='./api.json' json-sample-expand-level='all'></redoc>

关键点说明：

• 参数名转换：jsonSampleExpandLevel → json-sample-expand-level
• 值类型：使用字符串'all'表示完全展开
• 配置位置：直接作为redoc标签的属性设置

技术原理

ReDoc在解析HTML标签属性时：

1. 会自动将kebab-case属性名转换为camelCase
2. 优先处理直接属性配置，其次才会解析theme对象
3. 对于展开级别这类常用参数，提供了快捷配置方式

最佳实践建议

1. 对于简单配置，优先使用直接属性方式
2. 复杂主题定制才需要使用theme对象
3. 注意属性名的大小写转换规则
4. 测试时先从简单配置开始，逐步增加复杂度

通过理解这些技术细节，开发者可以更高效地使用ReDoc生成符合需求的API文档展示效果。