swagger - 如何重用 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

但是，在定义“Application”对象的“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$