OpenAPI 3.0/3.1中info.description是否允许使用$ref？

问题根源 #

1. 官方OpenAPI规范限制：根据OpenAPI标准，info.description字段的类型必须是字符串，不允许是包含$ref的对象。$ref在官方规范中的作用是替换整个字段（仅适用于对象/数组类型的字段），不能用于字符串字段的内容引用。
2. Redocly的扩展特性：Redocly CLI对OpenAPI规范做了自定义扩展，支持通过嵌套$ref的方式引用外部文件中的字符串内容。在执行redocly lint或生成文档时，Redocly会自动预处理这个$ref，将目标文件的内容转为字符串赋值给description，因此能正常工作。
3. VS的严格验证：Visual Studio中用于OpenAPI验证的工具（如内置的OpenAPI支持或第三方插件）严格遵循官方规范，识别到description是对象而非字符串时，就会抛出错误。

解决方法 #

方法1：遵循官方规范调整写法（推荐） #

将外部文件的内容直接写入description字段，或者使用YAML多行字符串语法：

info:
  description: |
    这里粘贴info-description.md文件中的所有内容
    支持多行文本格式

这种写法能保证在所有OpenAPI工具中都兼容，不会出现验证错误。

方法2：保留Redocly写法并让VS停止报错 #

如果坚持使用Redocly的扩展写法，可以通过以下方式消除VS的错误提示：

• 禁用VS的OpenAPI验证插件：关闭如"OpenAPI Editor"、"Swagger Viewer"这类会进行规范验证的插件。
• 调整VS设置：找到对应验证工具的设置项，关闭对info.description字段的类型检查。
• 使用Redocly的VS插件：安装Redocly官方提供的VS插件（若有），让VS使用Redocly的lint逻辑进行验证，而非官方规范的严格检查。

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