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

Question

我正在尝试在 OpenAPI 3.0.2 规范中定义架构。我想要其中一个属性根据值列表进行验证。

通常，我会使用枚举来执行此操作。

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'

缺少属性:$ref

应该完全匹配 oneOf 中的一个模式

enum 行导致

应该是数组

这样做的方法是什么？

Answer 1

“ Vanilla ”OpenAPI

OpenAPI 规范只允许在某些情况下使用 $ref，而不是在所有情况下。不可能只$ref enum 值列表，但您可以$ref 整个属性模式:

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

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

上面的例子假设 list.yaml 文件包含:

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

使用预处理器

也就是说，有诸如 json-refs 之类的工具或 openapi-preprocessor可以在文档的任何位置解析 JSON 引用和 JSON 指针。您可以使用它们来预处理问题中的原始规范，这将生成一个有效的已解析 OpenAPI 定义，然后可以与兼容 OpenAPI 的工具一起使用。