Swagger 用于值验证的远程枚举列表-在OpenAPI规范中

我试图在OpenAPI 3.0.2规范中定义模式。 我希望其中一个属性根据值列表进行验证

通常情况下，我可以使用enum执行此操作

components:
  schemas:
    catalog:
      title: title here
      description: describing it here
      properties:
        catalogitemid:
          description: catalog identifier
          type: string
          enum: 
            - item1347
            - item9081
            - item5720
        catalogitemname:
          description: catalog item name
          type: string
      required:
        - catalogitemid
        - catalogitemname
      additionalProperties: false

但是我希望这个枚举列表是一个远程YAML/JSON

原因：此列表需要定期更新（2000+个值）。我想避免强制更新这个API

低于$ref的方法失败：

components:
  schemas:
    catalog:
      title: title here
      description: describing it here
      properties:
        catalogitemid:
          description: catalog identifier
          type: string
          enum:
            $ref: 'https://remote/path/to/catalog/list.yaml#/components/schemas/catalogitemid/enum'
        catalogitemname:
          description: catalog item name
          type: string
      required:
        - catalogitemid
        - catalogitemname
      additionalProperties: false

错误：

行

目录

原因

应具有必需的属性“$ref”

missingProperty:$ref

应与其中一个中的一个架构完全匹配

和行

enum

原因

应该是数组

这样做的方法是什么？

“香草”OpenAPI OpenAPI规范只允许在某些上下文中使用

$ref

，而不是在任何地方。不能仅使用

$ref

枚举值列表，但可以

$ref

整个属性架构：

属性：
catalogitemid:
$ref:'https://remote/path/to/catalog/list.yaml#/components/schemas/catalogitemid'

以上假设

list.yaml

文件包含：

组件：
模式：
catalogitemid:
描述：目录标识符
类型：字符串
枚举：
-项目1347
-项目9081
-项目5720
...

使用预处理器

---

也就是说，有一些工具，例如或，可以解析文档中任何位置的JSON引用和JSON指针。您可以使用它们来预处理问题中的原始规范，这将生成一个有效的已解析OpenAPI定义，然后可以与符合OpenAPI的工具一起使用。

这可以通过将

catalogitemid

的整个模式定义推送到远程YAML来实现。这是我需要避免的。似乎不支持将枚举仅推送到远程，尽管这种需求情况似乎非常有效。@C.Derx您可以使用预处理器在不支持的位置解析$refs。我更新了答案。主API文档仍然需要每次更新。不过，谢谢你指出这一点，我相信我能够在另一个环境中使用它。恐怕没有其他方法了。您可以在OpenAPI规范存储库中提交增强请求：。