From 41897bda2fa966e36554c716f4c02633a8be7b76 Mon Sep 17 00:00:00 2001
From: mathis-m <mathis.michel@outlook.de>
Date: Fri, 12 Feb 2021 11:38:42 +0100
Subject: [PATCH] feat(docs): explain JSON Schema components

Signed-off-by: mathis-m <mathis.michel@outlook.de>
---
 docs/customization/plug-points.md | 87 +++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)

diff --git a/docs/customization/plug-points.md b/docs/customization/plug-points.md
index 9d7303bb1e7..03df20904fa 100644
--- a/docs/customization/plug-points.md
+++ b/docs/customization/plug-points.md
@@ -41,3 +41,90 @@ const MultiplePhraseFilterPlugin = function() {
   }
 }
 ```
+
+### JSON Schema components
+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:**
+```js
+`JsonSchema_${type}_${format}`
+```
+
+**Fallback if `JsonSchema_${type}_${format}` component does not exist or format not defined:**
+```js
+`JsonSchema_${type}`
+```
+
+**Default:**
+```js
+`JsonSchema_string`
+```
+
+With this, one can define custom input components or override existing.
+
+#### Example Date-Picker plugin
+
+If one would like to input date values you could provide a custom plugin to integrate [react-datepicker](https://www.npmjs.com/package/react-datepicker) into swagger-ui.
+All you need to do is to create a component to wrap [react-datepicker](https://www.npmjs.com/package/react-datepicker) accordingly to the format.
+
+**There are two cases:**
+- ```yaml
+  type: string
+  format: date
+  ```
+  The resulting name for mapping to succeed: `JsonSchema_string_date`
+- ```yaml
+  type: string
+  format: date-time
+  ```
+  The resulting name for mapping to succeed: `JsonSchema_string_date-time`
+
+This creates the need for two components and simple logic to strip any time input in case the format is date:
+```js
+import React from "react";
+import DatePicker from "react-datepicker";
+import "react-datepicker/dist/react-datepicker.css";
+
+const JsonSchema_string_date = (props) => {
+  const dateNumber = Date.parse(props.value);
+  const date = dateNumber
+    ? new Date(dateNumber)
+    : new Date();
+
+  return (
+    <DatePicker
+      selected={date}
+      onChange={d => props.onChange(d.toISOString().substring(0, 10))}
+    />
+  );
+}
+
+const JsonSchema_string_date_time = (props) => {
+  const dateNumber = Date.parse(props.value);
+  const date = dateNumber
+    ? new Date(dateNumber)
+    : new Date();
+
+  return (
+    <DatePicker
+      selected={date}
+      onChange={d => props.onChange(d.toISOString())}
+      showTimeSelect
+      timeFormat="p"
+      dateFormat="Pp"
+    />
+  );
+}
+
+
+export const DateTimeSwaggerPlugin = {
+  components: {
+    JsonSchema_string_date: JsonSchema_string_date,
+    "JsonSchema_string_date-time": JsonSchema_string_date_time
+  }
+};
+```