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

Posted 2023-02-19

【中文标题】如何重用 swagger 2.0 字符串模式定义？

【英文标题】：How to reuse swagger 2.0 string pattern definition?

【发布时间】：2019-01-21 23:37:26

【问题描述】：

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

definitions:
  TimeStamp:
    title: Timestamp format
    description: ISO 8681, "2016-08-18T17:33:00Z"
    type: string
    pattern: \d4-\d2-\d2T\d2:\d2:\d2Z
  Application:
    title: An application
    type: object
    properties:
      cDtm:
        title: Creation timestamp
        description: Some description
        type: string
        pattern:\d4-\d2-\d2T\d2:\d2:\d2Z

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

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

谢谢！

必应

【问题讨论】：

您是说 ISO 8601 吗？

它是 ISO 8601，但问题更笼统，关于如何使用新的标题和描述重用字符串模式定义

【参考方案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: ^\d4-\d2-\d2T\d2:\d2:\d2Z$

【讨论】：

感谢您指出“allOf”解决方案和 ^..$ 表达式。是的，这就是我要找的。​​span>