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

Question

我试图在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个值）。我想避免这迫使更新这个应用编程接口。

低于$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原因

应该是数组

有什么方法可以做到这一点？

Answer 1

OpenAPI规范只允许在某些上下文中使用$ref，而不是在任何地方。不能仅使用$ref枚举值列表，但可以$ref整个属性架构：

# This won't work
enum:
  $ref: 'https://...'

# This will work
properties:
  catalogitemid:
    $ref: 'https://remote/path/to/enums/catalog-list.yaml'

上面的示例假设列表。yaml文件包含：

description: catalog identifier
type: string
enum: 
  - item1347
  - item9081
  - item5720
  ...

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