如何在 Swagger 上记录 \"Retry-After\" HTTP-Date 格式？答案

【问题标题】：How to document "Retry-After" HTTP-Date format on Swagger?如何在 Swagger 上记录 \"Retry-After\" HTTP-Date 格式？
【发布时间】：2022-10-25 04:08:07
【问题描述】：

试图在 swagger（as described here 和 here）上以 HTTP-Date 格式记录 Retry-After 的响应标头。

您还可以在这里找到正在使用的语法：https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Date

句法：

Date: <day-name>, <day> <month> <year> <hour>:<minute>:<second> GMT

我的问题是描述此标头的最佳方式是什么，以及在使用 swagger 时哪种格式是正确的？

date/date-time/http-date?

大摇大摆的 openAPI-3

谢谢。

【问题讨论】：

标签： swagger openapi

【解决方案1】：

对于这种格式的日期，OpenAPI 和 JSON Schema 没有内置的 format。但是，format 是一个开放值关键字，因此您可以指定任何您喜欢的值，例如 format: http-date 甚至

format: <day-name>, <day> <month> <year> <hour>:<minute>:<second> GMT

无法识别给定format 值的工具将忽略它并仅使用type。

也就是说，我建议您使用不带format 的type: string，并可选择提供example 值。或者您可以将其设为字符串和整数的oneOf，以反映替代格式Retry-After: 120。（然而，一个简单的type: string 也适用于这种情况。）

使用type: string 的示例：

responses:
  '429':
    description: Rate limit exceeded
    headers:
      Retry-After:
        description: Indicates how long the client should wait before making a follow-up request. 
        schema:
          type: string
          # example: 'Wed, 21 Oct 2022 07:28:00 GMT'

        # optionally add examples for both date and delay-seconds
        examples:
          http-date:
            value: 'Wed, 21 Oct 2022 07:28:00 GMT'
          delay-seconds:
            value: 120

使用type: string + type: integer 的示例：

        schema:
          oneOf:
            - type: string
              example: 'Wed, 21 Oct 2022 07:28:00 GMT'
              description: A date after which to retry.
            - type: integer
              minimum: 0
              example: 120
              description: The seconds to delay after the response is received.

【讨论】：