没有固定属性列表的对象的 Swagger Yaml 架构定义

Posted 2023-03-08

【中文标题】没有固定属性列表的对象的 Swagger Yaml 架构定义

【英文标题】：Swagger Yaml schema definition for object without a fixed property list

【发布时间】：2016-10-31 12:32:20

【问题描述】：

我正在 Swagger 的帮助下实现一个 API 优先的应用程序。要返回的最重要的对象之一是 DICOM 对象，它返回具有灵活名称的属性集合，例如：

 
  "00080005": "vr":"CS","Value":["ISO_IR 100"],
  "00080020": "vr":"DA","Value":["20160602"],
  "00080030": "vr":"TM","Value":["171855.7490"],
  "00080050": "vr":"SH","Value":["1234"],
  "00080090": "vr":"PN","Value":["Alphabetic":"Parikh MD^Anush^M"]

所以我无法提前知道所有属性的名称（00080005、00080030等），虽然文件结构很统一。

我的具体问题是：这种 JSON 文档的架构定义是什么。

我尝试了以下方法但没有成功：

definitions:
  DicomMetadataJson:
    type: object
    patternProperties:
      ^\d8:
        type: object      

但 Swagger 编辑器返回如下错误：

代码：“OBJECT_ADDITIONAL_PROPERTIES”

消息：“不允许使用其他属性：patternProperties”

描述：“JSON Schema 对象的确定性版本。”

【问题讨论】：

我在 Swagger 规范中阅读了以下内容，但没有关于它的示例： 架构公开了两种类型的字段。具有声明名称的固定字段和声明字段名称的正则表达式模式的模式字段。模式化的字段可以多次出现，只要每个都有唯一的名称。

完全一样 - 它说你可以做到，但没有说明如何

【参考方案1】：

OpenAPI (fka. Swagger) 仅使用 JSON Schema v4 的一个子集，遗憾的是，它不建议 patternProperties。

但鉴于提供的示例是一张地图，您可以使用 additionalProperties 来描述它：

swagger: "2.0"
info:
  version: 1.0.0
  title: Hashmap

paths: 

definitions:
  DicomMetadataJson:
    additionalProperties:
      properties:
        vr:
          type: string
        Value:
          type: array
          items:
            type: string

密钥没有定义，应该是一个字符串（因此你不能强制它的格式）。

请注意，SwaggerUI Swagger UI 目前不渲染它们。问题在此处跟踪https://github.com/swagger-api/swagger-ui/issues/1248

与此同时，您可以使用此技巧定义地图对象相同类型的非必需属性（在下面的示例中为默认值），并在描述中给出一些提示：

swagger: "2.0"
info:
  version: 1.0.0
  title: Hashmap

paths: 

definitions:
  MetaData:
    properties:
      vr:
        type: string
      Value:
        type: array
        items:
          type: string

  DicomMetadataJson:
    description: 'A <string,MetaData> map, default key is only for documentation purpose'
    properties:
      default:
        $ref: '#/definitions/MetaData'
    additionalProperties:
      $ref: '#/definitions/MetaData'

关于报价架构公开了两种类型的字段。具有声明名称的固定字段和声明字段名称的正则表达式模式的模式字段。模式化的字段可以多次出现，只要每个都有一个唯一的名称。，它涉及 OpenAPI 规范本身的格式，而不是 OpenAPI 规范中描述的 API 使用的对象。

【讨论】：

这真的非常令人失望，因为 RAML 等其他 API 语言确实支持模式并且以非常简洁的方式。

同意，RAML 更适合模式，但缺乏离线工具 :( 无论如何都赢不了 - 似乎 API 定义领域目前一团糟

这仍然是真的吗？

@CMCDragonkai 仍然是这样，但是patternProperties 是在OpenAPI 3.1 中实现的，目前是RC1，他们称它们为patterned fields ：github.com/OAI/OpenAPI-Specification/blob/master/versions/…