Customizing swagger-ui: date picker

A common example for a date parameter could be filtering for dates by providing a query parameter with date format in order to return items that are newer than a timestamp.

Writing a date value as string is not convenient and is no satisfying user experience.

In case you want to add a date-picker functionality to swagger-ui the plugin system can be used to accomplish this.

Swagger UI exposes most of its internal logic through the plugin system.

This can be used to achieve custom behavior or to add new functionality.

Let’s dive into some internal background to accomplish the task of rendering a custom date-picker for date parameters.

In swagger there are so called JSON Schema components. These are used to render inputs for parameters and components of request bodies with application/x-www-form-urlencoded or multipart/* media-type.

Internally swagger uses following mapping to find the JSON Schema component from OpenAPI Specification schema information:

For each schema’s type(eg. `string`, `array`, …) and if defined schema’s format (eg. ‘date’, ‘uuid’, …) there is a corresponding component mapping:

If format defined:

If “JsonSchema_{type}_${format}” component does not exist or format not defined:

Default:

In OpenAPI Specification string schemas can have two format in case of dates.

1. only date information:

case schema’s type is “string” and format is “date”

The resulting name for mapping to succeed: “JsonSchema_string_date”.

2. date and time information:

case schema’s type is “string” and format is “date-time”

The resulting name for mapping to succeed: “JsonSchema_string_date-time”.

This creates the need for two components that will use react-datepicker to render a date picker.
Note in case of format date there is the need to strip the time information.

In order to integrate and test this plugin configure swagger-ui with the following parameters:

The result looks like this:

swagger-ui with react-datepicker

The preview is also available at codesandbox: