kin-openapi 项目中关于 externalValue 属性验证问题的解析

问题背景

在使用 kin-openapi 这个 Go 语言的 OpenAPI 规范解析库时，开发者遇到了一个关于示例值验证的问题。具体场景是在 OpenAPI 规范中使用 externalValue 属性引用外部示例文件时，遇到了两个验证错误。

问题现象

开发者在 OpenAPI 规范中定义了如下结构：

application/json:
  schema:
    $ref: '#/components/schemas/ErrorBaseResponse'
  examples:
    response:
      externalValue: "responseExamplesError.tmpl"
      value:
        ambit: "validation"
        message: "string"
        timestamp: "2022-03-28T12:55:03+02:00"

升级到最新版本(v0.92.0)后，遇到了两个验证问题：

1. 当同时使用 value 和 externalValue 属性时，会收到"value 和 externalValue 是互斥的"错误
2. 移除 value 属性只保留 externalValue 后，又收到"Value 不可为空"的错误

问题分析

互斥属性验证

根据 OpenAPI 3.0 规范，value 和 externalValue 确实是互斥的属性，不能同时存在。kin-openapi 库严格执行了这一规范，因此当两者同时出现时会报错。

非空验证问题

当只使用 externalValue 时，kin-openapi 的验证逻辑会检查示例值是否可为空。由于开发者定义的响应对象 ErrorBaseResponse 没有标记为 nullable: true，验证器认为这是一个必须包含值的字段，因此报错。

解决方案

对于这个问题，有几种处理方式：

1. 最佳实践：完全移除 value 属性，只保留 externalValue，并在引用的外部文件中提供完整的示例内容

2. 修改模式定义：如果确实需要保持响应对象为非空，可以在模式定义中添加 nullable: true

3. 禁用示例验证：如果不需要严格的示例验证，可以通过配置禁用这部分验证

openapi3.DisableExamplesValidation()

技术建议

1. 在使用外部示例文件时，确保外部文件内容与模式定义匹配
2. 考虑将示例内容完全外部化，而不是部分内联部分外部
3. 对于复杂的响应对象，明确指定其可空性可以避免验证问题
4. 在升级库版本时，注意验证规则的变更，特别是对于严格模式的增强

总结

kin-openapi 对 OpenAPI 规范的实现较为严格，特别是在验证方面。开发者在使用外部示例文件时需要注意规范要求，合理设计 API 定义结构。通过理解库的验证逻辑和 OpenAPI 规范要求，可以避免这类验证错误，编写出更加规范的 API 文档。