1. Introduction

1.绪论

In this tutorial, we’ll see how to declare dates in an OpenAPI file, in this case, implemented with Swagger. This will allow us to manage input and output dates in a standardized way when calling external APIs.

在本教程中，我们将看到如何在OpenAPI文件中声明日期，在这种情况下，用Swagger实现。这将使我们在调用外部API时能够以标准化的方式管理输入和输出日期。

2. Swagger vs. OAS

2.斯瓦格对OAS

Swagger is a set of tools implementing the OpenAPI Specification (OAS), a language-agnostic interface to document RESTful APIs. This allows us to understand the capabilities of any service without accessing the source code.

Swagger是一套实现OpenAPI Specification（OAS）的工具，这是一个记录RESTful APIs的语言无关的接口。这使我们能够在不访问源代码的情况下了解任何服务的能力。

To implement this, we’ll have a file in our project, typically YAML or JSON, describing APIs using OAS. We’ll then use Swagger tools to:

为了实现这一点，我们在项目中会有一个文件，通常是YAML或JSON,描述使用OAS的API。然后我们将使用Swagger工具来。

edit our specification through a browser (Swagger Editor)
auto-generate API client libraries (Swagger Codegen)
show auto-generated documentation (Swagger UI)

The OpenAPI file example contains different sections, but we’ll focus on the model definition.

OpenAPI文件示例包含不同的部分，但我们将专注于模型定义。

3. Defining a Date

3.定义一个日期

Let’s define a User entity using the OAS:

让我们使用OAS定义一个User实体。

components:
  User:
    type: "object"
    properties:
      id:
        type: integer
        format: int64
      createdAt:
        type: string
        format: date
        description: Creation date
        example: "2021-01-30"
      username:
        type: string

To define a date, we use an object with:

为了定义一个日期，我们使用一个具有以下特征的对象。

the type field equals to string
the format field which specifies how the date is formed

In this case, we used the date format to describe the createdAt date. This format describes dates using the ISO 8601 full-date format.

在这种情况下，我们使用date格式来描述createdAt日期。这种格式使用ISO 8601 full-date格式描述日期。

4. Defining a Date-Time

4.定义一个日期-时间

Additionally, if we also want to specify the time, we’ll use date-time as the format. Let’s see an example:

此外，如果我们还想指定时间，我们将使用date-time 作为格式.让我们看一个例子。

createdAt:
  type: string
  format: date-time
  description: Creation date and time
  example: "2021-01-30T08:30:00Z"

In this case, we’re describing date-times using the ISO 8601 full-time format.

在这种情况下，我们使用ISO 8601 full-time格式来描述日期-时间。

5. The pattern Field

5.pattern字段

Using OAS, we can describe dates with other formats as well. To do so, let’s use the pattern field:

使用OAS，我们也可以用其他格式来描述日期。要做到这一点，让我们使用pattern字段。

customDate: 
  type: string 
  pattern: '^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$'
  description: Custom date 
  example: "20210130"

Clearly, this is the less readable method, but the most powerful. Indeed, we can use any regular expression in this field.

显然，这是不太容易阅读的方法，但却是最强大的。事实上，我们可以在这个领域使用任何正则表达式。

6. Conclusion

6.结语

In this article, we’ve seen how to declare dates using OpenAPI. We can use standard formats offered by OpenAPI as well as custom patterns to match our needs. As always, the source code of the example we used is available over on GitHub.

在这篇文章中，我们已经看到了如何使用OpenAPI来声明日期。我们可以使用OpenAPI提供的标准格式，也可以使用自定义模式来满足我们的需求。像往常一样，我们所使用的例子的源代码可以在GitHub上找到。