如何重用 swagger 2.0 字符串模式定义？

Question

我在 swagger 2.0“定义”部分定义了以下内容。我首先定义了用于不同目的的许多对象属性中的时间戳格式，例如创建的时间戳和最后更新的时间戳。

definitions:
  TimeStamp:
    title: Timestamp format
    description: ISO 8681, "2016-08-18T17:33:00Z"
    type: string
    pattern: \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z
  Application:
    title: An application
    type: object
    properties:
      cDtm:
        title: Creation timestamp
        description: Some description
        type: string
        pattern:\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z

但是，在定义“应用程序”对象的“cDtm”属性时，我找不到重用时间戳定义的方法。如果我将 "$ref" 与 "title" 和 "description" 一起使用，我会收到警告“不允许在 '$ref' 旁边使用兄弟值”。如果我不使用“$ref”，我需要重复上面的类型和模式定义。

那么，我的问题是，有没有办法使用 $ref 来重用字符串模式定义，但仍然能够给定义的属性一个新的标题和描述？

谢谢！

必应

Answer 1

OpenAPI 规范包括此格式的内置 format: date-time，因此您实际上不需要在此处使用 pattern。相反，使用：

type: string
format: date-time

如果出于某种原因，您想坚持使用pattern，您可以使用以下解决方法。基本上，如果将$ref 包装到allOf 中，则可以将属性“添加”到$ref。这适用于 Swagger Editor 和 Swagger UI，但其他工具支持可能会有所不同。

  Application:
    title: An application
    type: object
    properties:
      cDtm:
        title: Creation timestamp
        description: Some description

        allOf:
          - $ref: '#/definitions/TimeStamp'

还请记住，pattern 默认情况下用作部分匹配。要强制完全匹配，请将模式表达式包含在 ^..$ 中：

pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$