1. Introduction
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.
2. Swagger vs. 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.
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:
- 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.
3. Defining a Date
Let’s define a User entity using the OAS:
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.
4. Defining a Date-Time
Additionally, if we also want to specify the time, we’ll use date-time as the format*.* Let’s see an example:
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.
5. The pattern Field
Using OAS, we can describe dates with other formats as well. To do so, let’s use the pattern field:
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
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.