Expand Authors Top

If you have a few years of experience in the Java ecosystem and you’d like to share that with the community, have a look at our Contribution Guidelines.

November Discount Launch 2022 – Top
We’re finally running a Black Friday launch. All Courses are 30% off until next Friday:


November Discount Launch 2022 – TEMP TOP (NPI)
We’re finally running a Black Friday launch. All Courses are 30% off until next Friday:


Expanded Audience – Frontegg – Security (partner)
announcement - icon User management is very complex, when implemented properly. No surprise here.

Not having to roll all of that out manually, but instead integrating a mature, fully-fledged solution - yeah, that makes a lot of sense.
That's basically what Frontegg is - User Management for your application. It's focused on making your app scalable, secure and enjoyable for your users.
From signup to authentication, it supports simple scenarios all the way to complex and custom application logic.

Have a look:

>> Elegant User Management, Tailor-made for B2B SaaS

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:

    type: "object"
        type: integer
        format: int64
        type: string
        format: date
        description: Creation date
        example: "2021-01-30"
        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:

  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:

  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.

November Discount Launch 2022 – Bottom
We’re finally running a Black Friday launch. All Courses are 30% off until next Friday:


Generic footer banner
Comments are closed on this article!