在 OpenAPI/Swagger 文件中声明日期的正确方法是什么? [英] What is the correct way to declare a date in an OpenAPI / Swagger-file?

问题描述

在 swagger-file 对象中声明日期的正确方法是什么?我认为是:

What is the correct way to declare a date in a swagger-file object? I would think it is:

  startDate:
    type: string
    description: Start date
    example: "2017-01-01"
    format: date

但我看到很多这样的声明:

But I see a lot of declarations like these:

  startDate:
    type: string
    description: Start date
    example: "2017-01-01"
    format: date
    pattern: "YYYY-MM-DD"
    minLength: 0
    maxLength: 10

谢谢.

推荐答案

OpenAPI Specification 说你必须使用:

类型:字符串格式:日期#或日期时间

type: string format: date # or date-time

支持的模式在 RFC 3339 中定义，第 5.6 节(实际上是 ISO 8601)和示例在第 5.8 节中提供.所以对于 date 值应该看起来像2018-03-20".对于 date-time，2018-03-20T09:12:28Z".因此，当使用 date 或 date-time 时，pattern 是不必要的，实际上应该省略.

The patterns supported are defined in RFC 3339, section 5.6 (effectively ISO 8601) and examples are provided in section 5.8. So for date values should look like "2018-03-20" and for date-time, "2018-03-20T09:12:28Z". As such, when using date or date-time, the pattern is unnecessary and in fact, should be omitted.

如果您需要支持格式不同于 RFC 3339 的日期/时间，则不允许将参数指定为 format: date 或 格式:日期时间.相反，您应该使用适当的 pattern 指定 format: string.

If you need to support dates/times formatted in a way that differs to RFC 3339, you are not allowed to specify your parameter as format: date or format: date-time. Instead, you should specify format: string with an appropriate pattern.

最后，请注意 YYYY-MM-DD" 的 pattern 根据规范是无效的:pattern 必须是正则表达式，不是占位符或格式字符串.

Finally, note that a pattern of "YYYY-MM-DD" is invalid according to the specification: pattern must be a regular expression, not a placeholder or format string.

如果您违反上述任何规则来解决根据 OpenAPI 规范生成 UI 的工具中的错误，您应该强烈考虑使用该工具提出这些错误，而不是生成无效的 OpenAPI 规范来解决此问题.

If you are violating any of the above rules to work around bugs in tools that generate UIs from OpenAPI specifications, you should strongly consider raising these bugs with that tool, rather than generating an invalid OpenAPI spec to work around this.

这篇关于在 OpenAPI/Swagger 文件中声明日期的正确方法是什么?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！