From 63ee245d3d5d4521d45bbfdbee0f52f296cd46d8 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Thu, 4 Apr 2024 14:14:24 +0200
Subject: [PATCH 01/41] feat(open-api): add open-api typescript types

closes INT-407
---
 package.json | 1 +
 yarn.lock    | 8 ++++++++
 2 files changed, 9 insertions(+)

diff --git a/package.json b/package.json
index 519e2972..c0923698 100755
--- a/package.json
+++ b/package.json
@@ -81,6 +81,7 @@
     "markdown-it-multimd-table": "^4.1.3",
     "mock-fs": "^5.1.2",
     "only-allow": "^1.1.1",
+    "openapi-types": "^12.1.3",
     "plop": "^4.0.0",
     "postcss-import": "^15.1.0",
     "prettier": "^2.8.8",
diff --git a/yarn.lock b/yarn.lock
index 5da7bf24..900e3b67 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1002,6 +1002,7 @@ __metadata:
     markdown-it-multimd-table: ^4.1.3
     mock-fs: ^5.1.2
     only-allow: ^1.1.1
+    openapi-types: ^12.1.3
     plop: ^4.0.0
     postcss-import: ^15.1.0
     prettier: ^2.8.8
@@ -7480,6 +7481,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"openapi-types@npm:^12.1.3":
+  version: 12.1.3
+  resolution: "openapi-types@npm:12.1.3"
+  checksum: 7fa5547f87a58d2aa0eba6e91d396f42d7d31bc3ae140e61b5d60b47d2fd068b48776f42407d5a8da7280cf31195aa128c2fc285e8bb871d1105edee5647a0bb
+  languageName: node
+  linkType: hard
+
 "opener@npm:^1.5.1":
   version: 1.5.2
   resolution: "opener@npm:1.5.2"

From 09053b84ba558f0ee650194b016504166e354b4b Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Thu, 4 Apr 2024 14:20:55 +0200
Subject: [PATCH 02/41] feat(open-api): add display of base open-api info and
 component structure

closes INT-407
---
 .../client/components/global/OpenApi.vue      | 24 +++++++++++++++++++
 .../client/components/global/OpenApiInfo.vue  | 17 +++++++++++++
 .../theme/client/components/global/index.ts   |  2 ++
 3 files changed, 43 insertions(+)
 create mode 100644 src/.vuepress/theme/client/components/global/OpenApi.vue
 create mode 100644 src/.vuepress/theme/client/components/global/OpenApiInfo.vue

diff --git a/src/.vuepress/theme/client/components/global/OpenApi.vue b/src/.vuepress/theme/client/components/global/OpenApi.vue
new file mode 100644
index 00000000..20c9cc6c
--- /dev/null
+++ b/src/.vuepress/theme/client/components/global/OpenApi.vue
@@ -0,0 +1,24 @@
+<template>
+  <section class="open-api">
+    <OpenApiInfo :info="document.info" />
+
+    <article
+      v-for="(item, path) in document.paths"
+      :key="path">
+      <OpenApiPath
+        v-if="item"
+        :path="item"
+        :title="path" />
+    </article>
+  </section>
+</template>
+
+<script setup lang="ts">
+import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import OpenApiPath from './OpenApiPath.vue';
+import OpenApiInfo from './OpenApiInfo.vue';
+
+defineProps<{
+  document: OpenApiType.Document;
+}>();
+</script>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiInfo.vue b/src/.vuepress/theme/client/components/global/OpenApiInfo.vue
new file mode 100644
index 00000000..419e98b0
--- /dev/null
+++ b/src/.vuepress/theme/client/components/global/OpenApiInfo.vue
@@ -0,0 +1,17 @@
+<template>
+  <section class="open-api-info">
+    <hgroup>
+      <h2>{{ info.title }}</h2>
+      <p>(v{{ info.version }})</p>
+      <p v-if="info.description">{{ info.description }}</p>
+    </hgroup>
+  </section>
+</template>
+
+<script setup lang="ts">
+import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+
+defineProps<{
+  info: OpenApiType.Document['info'];
+}>();
+</script>
diff --git a/src/.vuepress/theme/client/components/global/index.ts b/src/.vuepress/theme/client/components/global/index.ts
index fc4ccbdd..96cf0ace 100644
--- a/src/.vuepress/theme/client/components/global/index.ts
+++ b/src/.vuepress/theme/client/components/global/index.ts
@@ -62,3 +62,5 @@ export {default as Shield} from './Shield';
 export {default as Stack} from './Stack.vue';
 
 export {default as TeamMember} from './TeamMember.vue';
+
+export {default as OpenApi} from './OpenApi.vue';

From ecc3814442cc0c795547d274bfb69adc2b586268 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Thu, 4 Apr 2024 14:21:55 +0200
Subject: [PATCH 03/41] feat(open-api): add display of (example) responses and
 base path information for open-api

closes INT-407
---
 .../client/components/global/OpenApiPath.vue  | 35 +++++++++++++
 .../components/global/OpenApiResponses.vue    | 50 +++++++++++++++++++
 2 files changed, 85 insertions(+)
 create mode 100644 src/.vuepress/theme/client/components/global/OpenApiPath.vue
 create mode 100644 src/.vuepress/theme/client/components/global/OpenApiResponses.vue

diff --git a/src/.vuepress/theme/client/components/global/OpenApiPath.vue b/src/.vuepress/theme/client/components/global/OpenApiPath.vue
new file mode 100644
index 00000000..de946c1c
--- /dev/null
+++ b/src/.vuepress/theme/client/components/global/OpenApiPath.vue
@@ -0,0 +1,35 @@
+<template>
+  <article class="open-api-path">
+    <h2>{{ title }}</h2>
+    <div
+      v-for="(operation, method) in path"
+      :key="method">
+      <!-- <OpenApiOperation :path="operation" :title="method" /> -->
+      <Badge type="success">{{ method }}</Badge>
+      <template v-if="typeof operation === 'object'">
+        <h3 v-if="'operationId' in operation">
+          {{ operation.operationId }}
+        </h3>
+        <p v-if="'summary' in operation">{{ operation.summary }}</p>
+        <p v-if="'description' in operation">{{ operation.description }}</p>
+
+        <!-- TODO: Parameters table -->
+
+        <OpenApiResponses
+          v-if="'responses' in operation"
+          :responses="operation.responses" />
+      </template>
+    </div>
+  </article>
+</template>
+
+<script setup lang="ts">
+import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import OpenApiResponses from './OpenApiResponses.vue';
+import Badge from './Badge.vue';
+
+defineProps<{
+  title: string;
+  path: OpenApiType.PathItemObject;
+}>();
+</script>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
new file mode 100644
index 00000000..66812369
--- /dev/null
+++ b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
@@ -0,0 +1,50 @@
+<template>
+  <div v-if="Object.entries(responseObjects)?.length">
+    <h4>Responses</h4>
+    <ul>
+      <li
+        v-for="(response, code) in responseObjects"
+        :key="code">
+        <h5>Status Code: {{ code }}</h5>
+        <p v-if="response.description">{{ response.description }}</p>
+        <div
+          v-for="(item, responseType) in response.content"
+          :key="responseType">
+          <h6>{{ responseType }}</h6>
+          <pre v-if="item.example">{{ item.example }}</pre>
+          <pre
+            v-for="(example, index) in item.examples"
+            v-else-if="item.examples"
+            :key="index"
+            >{{ example }}</pre
+          >
+        </div>
+      </li>
+    </ul>
+  </div>
+</template>
+
+<script setup lang="ts">
+import {computed, type ComputedRef} from 'vue';
+import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+
+const props = defineProps<{
+  responses: OpenApiType.ResponsesObject;
+}>();
+
+// Guard to check if the response is an OpenApiType.ResponseObject.
+const isReponseObject = (response: object): response is OpenApiType.ResponseObject => {
+  return typeof response === 'object';
+};
+
+// Adds a computed to get only the OpenApiType.ResponseObject types from the responses prop.
+const responseObjects: ComputedRef<Record<string, OpenApiType.ResponseObject>> = computed(() => {
+  const objects: Record<string, OpenApiType.ResponseObject> = {};
+  Object.entries(props.responses)
+    .filter((response): response is [string, OpenApiType.ResponseObject] => isReponseObject(response))
+    .forEach(([code, response]) => {
+      objects[code] = response;
+    });
+  return objects;
+});
+</script>

From 07481fa55c32326f57a2b77409901fe914bc3242 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Thu, 4 Apr 2024 15:43:47 +0200
Subject: [PATCH 04/41] feat(open-api): improve display of open-api operation
 details

improves display of the path/method  and adds placeholder security details

closes INT-407
---
 .../components/global/OpenApiOperation.vue    | 40 +++++++++++++++++++
 .../client/components/global/OpenApiPath.vue  | 12 ++++--
 2 files changed, 48 insertions(+), 4 deletions(-)
 create mode 100644 src/.vuepress/theme/client/components/global/OpenApiOperation.vue

diff --git a/src/.vuepress/theme/client/components/global/OpenApiOperation.vue b/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
new file mode 100644
index 00000000..cb96195f
--- /dev/null
+++ b/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
@@ -0,0 +1,40 @@
+<template>
+  <header class="bg-gray-100 mb-4 mt-4 open-api-operation p-3">
+    <strong>Endpoint:</strong>
+    <pre
+      class="inline-block leading-none m-0 ml-3 p-1 rounded-sm text-sm"
+      :class="methodClass"
+      >{{ method.toUpperCase() }}</pre
+    >
+    <pre class="inline m-0 ml-2 p-0 text-gray-700 text-sm">{{ endpoint }}</pre>
+    <br />
+    <template v-if="authentication">
+      <strong>Authentication:</strong>&nbsp;
+      <pre>{{ authentication }}</pre>
+    </template>
+  </header>
+</template>
+
+<script setup lang="ts">
+import {computed} from 'vue';
+import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+
+const props = defineProps<{
+  method: string;
+  endpoint: string;
+  authentication?: OpenApiType.SecurityRequirementObject[] | null;
+}>();
+
+const methodClass = computed(() => {
+  return {
+    'bg-green-200': props.method === 'get',
+    'bg-blue-200': props.method === 'post',
+    'bg-yellow-200': props.method === 'put',
+    'bg-red-200': props.method === 'delete',
+    'bg-purple-200': props.method === 'patch',
+    'bg-gray-200': props.method === 'options',
+    'bg-indigo-200': props.method === 'head',
+    'bg-pink-200': props.method === 'trace',
+  };
+});
+</script>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiPath.vue b/src/.vuepress/theme/client/components/global/OpenApiPath.vue
index de946c1c..4760625d 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiPath.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiPath.vue
@@ -1,16 +1,20 @@
 <template>
   <article class="open-api-path">
-    <h2>{{ title }}</h2>
     <div
       v-for="(operation, method) in path"
       :key="method">
-      <!-- <OpenApiOperation :path="operation" :title="method" /> -->
-      <Badge type="success">{{ method }}</Badge>
       <template v-if="typeof operation === 'object'">
         <h3 v-if="'operationId' in operation">
           {{ operation.operationId }}
         </h3>
+
         <p v-if="'summary' in operation">{{ operation.summary }}</p>
+
+        <OpenApiOperation
+          :method="method"
+          :endpoint="title"
+          :authentication="'security' in operation ? operation.security : null" />
+
         <p v-if="'description' in operation">{{ operation.description }}</p>
 
         <!-- TODO: Parameters table -->
@@ -26,7 +30,7 @@
 <script setup lang="ts">
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
 import OpenApiResponses from './OpenApiResponses.vue';
-import Badge from './Badge.vue';
+import OpenApiOperation from './OpenApiOperation.vue';
 
 defineProps<{
   title: string;

From f73a61fc94967b424b4004eea4914d3e9f4ae991 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Thu, 4 Apr 2024 16:24:29 +0200
Subject: [PATCH 05/41] feat(open-api): display API responses using existing
 components

INT-407
---
 .../components/global/OpenApiResponses.vue    | 33 +++++++++++--------
 1 file changed, 20 insertions(+), 13 deletions(-)

diff --git a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
index 66812369..aafc9127 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
@@ -5,20 +5,13 @@
       <li
         v-for="(response, code) in responseObjects"
         :key="code">
-        <h5>Status Code: {{ code }}</h5>
+        <Http :code="code" />
         <p v-if="response.description">{{ response.description }}</p>
-        <div
-          v-for="(item, responseType) in response.content"
-          :key="responseType">
-          <h6>{{ responseType }}</h6>
-          <pre v-if="item.example">{{ item.example }}</pre>
-          <pre
-            v-for="(example, index) in item.examples"
-            v-else-if="item.examples"
-            :key="index"
-            >{{ example }}</pre
-          >
-        </div>
+
+        <CodeGroup
+          v-if="response.content"
+          :items="mapToCodegroup(response.content)">
+        </CodeGroup>
       </li>
     </ul>
   </div>
@@ -27,6 +20,8 @@
 <script setup lang="ts">
 import {computed, type ComputedRef} from 'vue';
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import Http from './Http.vue';
+import CodeGroup from './CodeGroup.vue';
 
 const props = defineProps<{
   responses: OpenApiType.ResponsesObject;
@@ -47,4 +42,16 @@ const responseObjects: ComputedRef<Record<string, OpenApiType.ResponseObject>> =
     });
   return objects;
 });
+
+// Maps the response content to a CodeGroupItem array.
+const mapToCodegroup = (content: Record<string, OpenApiType.MediaTypeObject>) => {
+  return Object.entries(content).map(([responseType, item]) => {
+    // @TODO support component references here, too
+    return {
+      title: responseType,
+      code: item.examples ?? item.examples ?? item.example,
+      language: responseType,
+    };
+  });
+};
 </script>

From 9954f01ba6fece42f1d5acecccff77eaebcb2287 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Thu, 4 Apr 2024 16:26:28 +0200
Subject: [PATCH 06/41] docs(open-api): add a test document for open-api output

INT-407
---
 src/api-reference/9999.test.md | 414 +++++++++++++++++++++++++++++++++
 1 file changed, 414 insertions(+)
 create mode 100644 src/api-reference/9999.test.md

diff --git a/src/api-reference/9999.test.md b/src/api-reference/9999.test.md
new file mode 100644
index 00000000..1d9bb748
--- /dev/null
+++ b/src/api-reference/9999.test.md
@@ -0,0 +1,414 @@
+---
+title: 9999. Test
+---
+
+<OpenApi :document="{
+  'openapi': '3.0.0',
+  'info': {
+    'version': '1.0.0',
+    'title': 'Swagger Petstore',
+    'description': 'A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification',
+    'termsOfService': 'http://swagger.io/terms/',
+    'contact': {
+      'name': 'Swagger API Team',
+      'email': 'apiteam@swagger.io',
+      'url': 'http://swagger.io'
+    },
+    'license': {
+      'name': 'Apache 2.0',
+      'url': 'https://www.apache.org/licenses/LICENSE-2.0.html'
+    }
+  },
+  'servers': [
+    {
+      'url': 'https://petstore.swagger.io/v2'
+    }
+  ],
+  'paths': {
+    '/pets': {
+      'get': {
+        'description': 'Returns all pets from the system that the user has access to\nNam sed condimentum est. Maecenas tempor sagittis sapien, nec rhoncus sem sagittis sit amet. Aenean at gravida augue, ac iaculis sem. Curabitur odio lorem, ornare eget elementum nec, cursus id lectus. Duis mi turpis, pulvinar ac eros ac, tincidunt varius justo. In hac habitasse platea dictumst. Integer at adipiscing ante, a sagittis ligula. Aenean pharetra tempor ante molestie imperdiet. Vivamus id aliquam diam. Cras quis velit non tortor eleifend sagittis. Praesent at enim pharetra urna volutpat venenatis eget eget mauris. In eleifend fermentum facilisis. Praesent enim enim, gravida ac sodales sed, placerat id erat. Suspendisse lacus dolor, consectetur non augue vel, vehicula interdum libero. Morbi euismod sagittis libero sed lacinia.\n\nSed tempus felis lobortis leo pulvinar rutrum. Nam mattis velit nisl, eu condimentum ligula luctus nec. Phasellus semper velit eget aliquet faucibus. In a mattis elit. Phasellus vel urna viverra, condimentum lorem id, rhoncus nibh. Ut pellentesque posuere elementum. Sed a varius odio. Morbi rhoncus ligula libero, vel eleifend nunc tristique vitae. Fusce et sem dui. Aenean nec scelerisque tortor. Fusce malesuada accumsan magna vel tempus. Quisque mollis felis eu dolor tristique, sit amet auctor felis gravida. Sed libero lorem, molestie sed nisl in, accumsan tempor nisi. Fusce sollicitudin massa ut lacinia mattis. Sed vel eleifend lorem. Pellentesque vitae felis pretium, pulvinar elit eu, euismod sapien.\n',
+        'operationId': 'findPets',
+        'parameters': [
+          {
+            'name': 'tags',
+            'in': 'query',
+            'description': 'tags to filter by',
+            'required': false,
+            'style': 'form',
+            'schema': {
+              'type': 'array',
+              'items': {
+                'type': 'string'
+              }
+            }
+          },
+          {
+            'name': 'limit',
+            'in': 'query',
+            'description': 'maximum number of results to return',
+            'required': false,
+            'schema': {
+              'type': 'integer',
+              'format': 'int32'
+            }
+          }
+        ],
+        'responses': {
+          '200': {
+            'description': 'pet response',
+            'content': {
+              'application/json': {
+                'schema': {
+                  'type': 'array',
+                  'items': {
+                    '$ref': '#/components/schemas/Pet'
+                  }
+                }
+              }
+            }
+          },
+          'default': {
+            'description': 'unexpected error',
+            'content': {
+              'application/json': {
+                'schema': {
+                  '$ref': '#/components/schemas/Error'
+                }
+              }
+            }
+          }
+        }
+      },
+      'post': {
+        'description': 'Creates a new pet in the store. Duplicates are allowed',
+        'operationId': 'addPet',
+        'requestBody': {
+          'description': 'Pet to add to the store',
+          'required': true,
+          'content': {
+            'application/json': {
+              'schema': {
+                '$ref': '#/components/schemas/NewPet'
+              }
+            }
+          }
+        },
+        'responses': {
+          '200': {
+            'description': 'pet response',
+            'content': {
+              'application/json': {
+                'schema': {
+                  '$ref': '#/components/schemas/Pet'
+                }
+              }
+            }
+          },
+          'default': {
+            'description': 'unexpected error',
+            'content': {
+              'application/json': {
+                'schema': {
+                  '$ref': '#/components/schemas/Error'
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    '/pets/{id}': {
+      'get': {
+        'description': 'Returns a user based on a single ID, if the user does not have access to the pet',
+        'operationId': 'find pet by id',
+        'parameters': [
+          {
+            'name': 'id',
+            'in': 'path',
+            'description': 'ID of pet to fetch',
+            'required': true,
+            'schema': {
+              'type': 'integer',
+              'format': 'int64'
+            }
+          }
+        ],
+        'responses': {
+          '200': {
+            'description': 'pet response',
+            'content': {
+              'application/json': {
+                'schema': {
+                  '$ref': '#/components/schemas/Pet'
+                }
+              }
+            }
+          },
+          'default': {
+            'description': 'unexpected error',
+            'content': {
+              'application/json': {
+                'schema': {
+                  '$ref': '#/components/schemas/Error'
+                }
+              }
+            }
+          }
+        }
+      },
+      'delete': {
+        'description': 'deletes a single pet based on the ID supplied',
+        'operationId': 'deletePet',
+        'parameters': [
+          {
+            'name': 'id',
+            'in': 'path',
+            'description': 'ID of pet to delete',
+            'required': true,
+            'schema': {
+              'type': 'integer',
+              'format': 'int64'
+            }
+          }
+        ],
+        'responses': {
+          '204': {
+            'description': 'pet deleted'
+          },
+          'default': {
+            'description': 'unexpected error',
+            'content': {
+              'application/json': {
+                'schema': {
+                  '$ref': '#/components/schemas/Error'
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  'components': {
+    'schemas': {
+      'Pet': {
+        'allOf': [
+          {
+            '$ref': '#/components/schemas/NewPet'
+          },
+          {
+            'type': 'object',
+            'required': [
+              'id'
+            ],
+            'properties': {
+              'id': {
+                'type': 'integer',
+                'format': 'int64'
+              }
+            }
+          }
+        ]
+      },
+      'NewPet': {
+        'type': 'object',
+        'required': [
+          'name'
+        ],
+        'properties': {
+          'name': {
+            'type': 'string'
+          },
+          'tag': {
+            'type': 'string'
+          }
+        }
+      },
+      'Error': {
+        'type': 'object',
+        'required': [
+          'code',
+          'message'
+        ],
+        'properties': {
+          'code': {
+            'type': 'integer',
+            'format': 'int32'
+          },
+          'message': {
+            'type': 'string'
+          }
+        }
+      }
+    }
+  }
+}" />
+
+<OpenApi :document="{
+  'openapi': '3.0.0',
+  'info': {
+    'title': 'Simple API overview',
+    'version': '2.0.0'
+  },
+  'paths': {
+    '/': {
+      'get': {
+        'operationId': 'listVersionsv2',
+        'summary': 'List API versions',
+        'responses': {
+          '200': {
+            'description': '200 response',
+            'content': {
+              'application/json': {
+                'examples': {
+                  'foo': {
+                    'value': {
+                      'versions': [
+                        {
+                          'status': 'CURRENT',
+                          'updated': '2011-01-21T11:33:21Z',
+                          'id': 'v2.0',
+                          'links': [
+                            {
+                              'href': 'http://127.0.0.1:8774/v2/',
+                              'rel': 'self'
+                            }
+                          ]
+                        },
+                        {
+                          'status': 'EXPERIMENTAL',
+                          'updated': '2013-07-23T11:33:21Z',
+                          'id': 'v3.0',
+                          'links': [
+                            {
+                              'href': 'http://127.0.0.1:8774/v3/',
+                              'rel': 'self'
+                            }
+                          ]
+                        }
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          '300': {
+            'description': '300 response',
+            'content': {
+              'application/json': {
+                'examples': {
+                  'foo': {
+                    'value': '{\n \'versions\': [\n       {\n         \'status\': \'CURRENT\',\n         \'updated\': \'2011-01-21T11:33:21Z\',\n         \'id\': \'v2.0\',\n         \'links\': [\n             {\n                 \'href\': \'http://127.0.0.1:8774/v2/\',\n                 \'rel\': \'self\'\n             }\n         ]\n     },\n     {\n         \'status\': \'EXPERIMENTAL\',\n         \'updated\': \'2013-07-23T11:33:21Z\',\n         \'id\': \'v3.0\',\n         \'links\': [\n             {\n                 \'href\': \'http://127.0.0.1:8774/v3/\',\n                 \'rel\': \'self\'\n             }\n         ]\n     }\n ]\n}\n'
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    '/v2': {
+      'get': {
+        'operationId': 'getVersionDetailsv2',
+        'summary': 'Show API version details',
+        'responses': {
+          '200': {
+            'description': '200 response',
+            'content': {
+              'application/json': {
+                'examples': {
+                  'foo': {
+                    'value': {
+                      'version': {
+                        'status': 'CURRENT',
+                        'updated': '2011-01-21T11:33:21Z',
+                        'media-types': [
+                          {
+                            'base': 'application/xml',
+                            'type': 'application/vnd.openstack.compute+xml;version=2'
+                          },
+                          {
+                            'base': 'application/json',
+                            'type': 'application/vnd.openstack.compute+json;version=2'
+                          }
+                        ],
+                        'id': 'v2.0',
+                        'links': [
+                          {
+                            'href': 'http://127.0.0.1:8774/v2/',
+                            'rel': 'self'
+                          },
+                          {
+                            'href': 'http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf',
+                            'type': 'application/pdf',
+                            'rel': 'describedby'
+                          },
+                          {
+                            'href': 'http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl',
+                            'type': 'application/vnd.sun.wadl+xml',
+                            'rel': 'describedby'
+                          },
+                          {
+                            'href': 'http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl',
+                            'type': 'application/vnd.sun.wadl+xml',
+                            'rel': 'describedby'
+                          }
+                        ]
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          '203': {
+            'description': '203 response',
+            'content': {
+              'application/json': {
+                'examples': {
+                  'foo': {
+                    'value': {
+                      'version': {
+                        'status': 'CURRENT',
+                        'updated': '2011-01-21T11:33:21Z',
+                        'media-types': [
+                          {
+                            'base': 'application/xml',
+                            'type': 'application/vnd.openstack.compute+xml;version=2'
+                          },
+                          {
+                            'base': 'application/json',
+                            'type': 'application/vnd.openstack.compute+json;version=2'
+                          }
+                        ],
+                        'id': 'v2.0',
+                        'links': [
+                          {
+                            'href': 'http://23.253.228.211:8774/v2/',
+                            'rel': 'self'
+                          },
+                          {
+                            'href': 'http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf',
+                            'type': 'application/pdf',
+                            'rel': 'describedby'
+                          },
+                          {
+                            'href': 'http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl',
+                            'type': 'application/vnd.sun.wadl+xml',
+                            'rel': 'describedby'
+                          }
+                        ]
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}" />

From c2a7dd1c9c881a24c53325f291843a2ed9d515c3 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Fri, 5 Apr 2024 10:04:42 +0200
Subject: [PATCH 07/41] fix(open-api): fix dark mode not working correctly for
 the operations block

INT-407
---
 .../theme/client/components/global/OpenApiOperation.vue     | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/.vuepress/theme/client/components/global/OpenApiOperation.vue b/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
index cb96195f..4eca37f3 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
@@ -1,12 +1,12 @@
 <template>
-  <header class="bg-gray-100 mb-4 mt-4 open-api-operation p-3">
+  <header class="bg-gray-100 dark:bg-gray-800 mb-4 mt-4 open-api-operation p-3">
     <strong>Endpoint:</strong>
     <pre
-      class="inline-block leading-none m-0 ml-3 p-1 rounded-sm text-sm"
+      class="dark:text-black inline-block leading-none m-0 ml-3 p-1 rounded-sm text-sm"
       :class="methodClass"
       >{{ method.toUpperCase() }}</pre
     >
-    <pre class="inline m-0 ml-2 p-0 text-gray-700 text-sm">{{ endpoint }}</pre>
+    <pre class="dark:text-gray-100 inline m-0 ml-2 p-0 text-gray-700 text-sm">{{ endpoint }}</pre>
     <br />
     <template v-if="authentication">
       <strong>Authentication:</strong>&nbsp;

From 722252210874ab0842b8c76453dbcb3d02060505 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Fri, 5 Apr 2024 10:55:30 +0200
Subject: [PATCH 08/41] docs(open-api): add json sample for MyParcel webhooks

INT-407
---
 src/api-reference/9999.test.md | 265 +++++++++++++++++++++++++++++++++
 1 file changed, 265 insertions(+)

diff --git a/src/api-reference/9999.test.md b/src/api-reference/9999.test.md
index 1d9bb748..146991ac 100644
--- a/src/api-reference/9999.test.md
+++ b/src/api-reference/9999.test.md
@@ -2,6 +2,271 @@
 title: 9999. Test
 ---
 
+<OpenApi :document="{
+  openapi: '3.1.0',
+  info: {
+    title: 'MyParcel Core-API',
+    contact: {
+      name: 'IT Support',
+      url: ':support@myparcel.nl'
+    },
+    version: '4.0.0'
+  },
+  servers: [
+    {
+      url: 'https://api.myparcel.nl',
+      description: 'MyParcel Production Server'
+    }
+  ],
+  paths: {
+    '/webhook_subscriptions': {
+      get: {
+        tags: ['Webhook Subscriptions'],
+        description: 'Show list of webhook subscriptions',
+        operationId: 'getSubscriptions',
+        parameters: [
+          { $ref: '#/components/parameters/user_agent_header' },
+          { $ref: '#/components/parameters/account_id' },
+          { $ref: '#/components/parameters/shop_id' },
+          {
+            name: 'hook',
+            in: 'query',
+            description: 'The event from which you want to receive notifications',
+            required: false,
+            schema: {
+              description: 'The event from which you want to receive notifications',
+              type: 'string',
+              example: 'shipment_status_change'
+            }
+          }
+        ],
+        responses: {
+          '200': {
+            description: 'OK',
+            content: {
+              'application/json; charset: utf-8': {
+                schema: {
+                  $ref: '#/components/schemas/webhook_subscriptions_response'
+                }
+              }
+            }
+          },
+          '400': { description: 'Validation error' },
+          '401': { description: 'Unauthorized' },
+          '403': { description: 'Forbidden' },
+          '500': { description: 'Internal Server Error' }
+        },
+        security: []
+      },
+      post: {
+        tags: ['Webhook Subscriptions'],
+        description: 'Add new webhook subscription.',
+        operationId: 'postSubscriptions',
+        parameters: [{ $ref: '#/components/parameters/user_agent_header' }],
+        requestBody: {
+          description: '|\n            | **Hook** | **Description** |\n            |---- |------------|\n            | ```shipment_status_change``` | Whenever the shipment_status of a shipment changes, this webhook will send you an update with the new value. We will not send an update with a status.|\n            | ```shipment_label_created``` | When a label is created asynchronously (for example when creating shipments using accept header ```application/vnd.shipment_label+json;charset=utf-8```), this webhook will send you a message with the URL of the label. |\n            | ```order_status_change``` | Whenever the order_status of an order changes, this webhook will send you an update with the new value. |',
+          required: true,
+          content: {
+            'application/json; charset: utf-8': {
+              schema: {
+                $ref: '#/components/schemas/webhook_subscription_request'
+              }
+            }
+          }
+        },
+        responses: {
+          '201': {
+            description: 'Response with array of webhook ids',
+            content: {
+              'application/json; charset: utf-8': {
+                example: {
+                  data: {
+                    webhook_subscriptions: [{ id: 1 }]
+                  }
+                }
+              }
+            }
+          },
+          '400': { description: 'Validation error' },
+          '401': { description: 'Unauthorized' },
+          '403': { description: 'Forbidden' },
+          '500': { description: 'Internal Server Error' }
+        },
+        security: []
+      }
+    },
+    '/webhook_subscriptions/{webhook_subscriptions_id}': {
+      delete: {
+        tags: ['Webhook Subscriptions'],
+        summary: 'Delete webhook subscriptions.',
+        description: 'Delete a webhook subscription',
+        operationId: 'deleteSubscriptions',
+        parameters: [
+          { $ref: '#/components/parameters/user_agent_header' },
+          { $ref: '#/components/parameters/webhook_subscriptions_id_in_path' }
+        ],
+        responses: {
+          '204': { description: 'No content' },
+          '401': { description: 'Unauthorized' },
+          '403': { description: 'Forbidden' },
+          '500': { description: 'Internal Server Error' }
+        },
+        security: []
+      }
+    }
+  },
+  components: {
+    schemas: {
+      webhook_subscriptions_response: {
+        required: ['data'],
+        properties: {
+          data: {
+            required: ['webhook_subscriptions'],
+            properties: {
+              webhook_subscriptions: {
+                type: 'array',
+                items: { $ref: '#/components/schemas/webhook_subscription' }
+              }
+            },
+            type: 'object'
+          }
+        },
+        type: 'object'
+      },
+      webhook_subscription: {
+        description: 'Webhook subscription',
+        required: ['id', 'account_id', 'shop_id', 'hook', 'url'],
+        properties: {
+          id: {
+            description: 'ID of webhook subscriptions',
+            type: 'integer',
+            format: 'int32',
+            example: 56123456
+          },
+          account_id: {
+            description: 'Account ID',
+            type: 'integer',
+            format: 'int32',
+            example: 125678
+          },
+          shop_id: {
+            description: 'Shop ID',
+            type: 'integer',
+            format: 'int32',
+            example: 1234
+          },
+          hook: {
+            description: 'The event from which you want to receive notifications',
+            type: 'string',
+            example: 'shipment_status_changed'
+          },
+          url: {
+            description: 'The callback URL on which to receive notifications',
+            type: 'string',
+            format: 'uri',
+            example: 'https://example.com/webhook'
+          }
+        },
+        type: 'object'
+      },
+      webhook_subscription_request: {
+        description: 'Webhook subscription request',
+        required: ['data'],
+        properties: {
+          data: {
+            required: ['webhook_subscription'],
+            properties: {
+              webhook_subscription: {
+                required: ['hook', 'url'],
+                properties: {
+                  hook: {
+                    description: 'The event from which you want to receive notifications',
+                    type: 'string',
+                    example: 'shipment_status_changed'
+                  },
+                  url: {
+                    description: 'The callback URL on which to receive notifications',
+                    type: 'string',
+                    format: 'uri',
+                    example: 'https://example.com/webhook'
+                  }
+                },
+                type: 'object'
+              }
+            },
+            type: 'object'
+          }
+        },
+        type: 'object'
+      }
+    },
+    parameters: {
+      account_id: {
+        name: 'account_id',
+        in: 'query',
+        description: 'The ID of the account.',
+        required: false,
+        schema: {
+          type: 'integer',
+          format: 'int32'
+        },
+        example: '123456'
+      },
+      shop_id: {
+        name: 'shop_id',
+        in: 'query',
+        description: 'The ID of the shop.',
+        required: false,
+        schema: {
+          type: 'integer',
+          format: 'int32'
+        },
+        example: '5678'
+      },
+      user_agent_header: {
+        name: 'User-Agent',
+        in: 'header',
+        description: 'The User-Agent header',
+        required: true,
+        schema: {
+          type: 'string'
+        },
+        example: 'NameOfMyApp/1.0.0 PHP/8.1.0'
+      },
+      webhook_subscriptions_id_in_path: {
+        name: 'webhook_subscriptions_id',
+        in: 'path',
+        description: 'The ID of the webhook subscription',
+        required: true,
+        schema: {
+          type: 'integer',
+          format: 'int32'
+        },
+        example: '123456789'
+      }
+    },
+    securitySchemes: {
+      bearerAuth: {
+        type: 'http',
+        description: 'BASE64 encoded ',
+        name: 'Authorization',
+        in: 'header',
+        scheme: 'bearer'
+      }
+    }
+  },
+  tags: [
+    {
+      name: 'Pickup Locations',
+      description: 'All about Pickup Locations'
+    },
+    {
+      name: 'Webhook Subscriptions',
+      description: 'All about Webhooks'
+    }
+  ]
+}" />
+
 <OpenApi :document="{
   'openapi': '3.0.0',
   'info': {

From 470a59ec8b31c90383d1ca62533132c2d0960d67 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Fri, 5 Apr 2024 12:03:40 +0200
Subject: [PATCH 09/41] fix(open-api): fix security / auth showing when it was
 an empty array

INT-407
---
 .../theme/client/components/global/OpenApiOperation.vue         | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/.vuepress/theme/client/components/global/OpenApiOperation.vue b/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
index 4eca37f3..75dbf8e6 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
@@ -8,7 +8,7 @@
     >
     <pre class="dark:text-gray-100 inline m-0 ml-2 p-0 text-gray-700 text-sm">{{ endpoint }}</pre>
     <br />
-    <template v-if="authentication">
+    <template v-if="authentication?.length">
       <strong>Authentication:</strong>&nbsp;
       <pre>{{ authentication }}</pre>
     </template>

From 9b04e08476b8added64c6bda3104f3c8e198b5b3 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Fri, 5 Apr 2024 12:57:00 +0200
Subject: [PATCH 10/41] feat(open-api): add basic $ref resolution support for
 openapi documents

adds support to resolve $ref references to paths within the document

INT-407
---
 .../client/components/global/OpenApi.vue      | 36 +++++++++++++++++--
 .../components/global/OpenApiResponses.vue    | 13 +++++--
 2 files changed, 44 insertions(+), 5 deletions(-)

diff --git a/src/.vuepress/theme/client/components/global/OpenApi.vue b/src/.vuepress/theme/client/components/global/OpenApi.vue
index 20c9cc6c..fed8f5a5 100644
--- a/src/.vuepress/theme/client/components/global/OpenApi.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApi.vue
@@ -1,9 +1,9 @@
 <template>
   <section class="open-api">
-    <OpenApiInfo :info="document.info" />
+    <OpenApiInfo :info="resolvedDocument.info" />
 
     <article
-      v-for="(item, path) in document.paths"
+      v-for="(item, path) in resolvedDocument.paths"
       :key="path">
       <OpenApiPath
         v-if="item"
@@ -14,11 +14,41 @@
 </template>
 
 <script setup lang="ts">
+import {computed} from 'vue';
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import {get} from 'lodash-es';
 import OpenApiPath from './OpenApiPath.vue';
 import OpenApiInfo from './OpenApiInfo.vue';
 
-defineProps<{
+const props = defineProps<{
   document: OpenApiType.Document;
 }>();
+
+const resolvedDocument = computed(() => resolveRefs(props.document));
+
+// Recursively loop through the entire document and replace any $ref keys with their corresponding values
+function resolveRefs(document: OpenApiType.Document): OpenApiType.Document {
+  const resolvedDocument = {...document};
+
+  function resolveRefsRecursive(obj: object | (string | number | object)[]) {
+    for (const key in obj) {
+      if (key === '$ref') {
+        const lookup = (obj as {$ref: string})[key];
+        // Lookup is a string that defines the path to the referenced object like '#/components/schemas/Example'
+        const path = lookup.split('/').slice(1);
+        // Find the referenced object in the document using lodash's get function
+        const referencedObject = get(resolvedDocument, path);
+        // Remove the $ref: '...' key from the object and replace it with the referenced object itself
+        obj = Object.assign(obj, referencedObject);
+      } else if (typeof obj[key] === 'object' || Array.isArray(obj[key])) {
+        // If the value is an object or an array, recursively call this function
+        resolveRefsRecursive(obj[key]);
+      }
+    }
+  }
+
+  resolveRefsRecursive(resolvedDocument);
+
+  return resolvedDocument;
+}
 </script>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
index aafc9127..e4a2fa6b 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
@@ -46,10 +46,19 @@ const responseObjects: ComputedRef<Record<string, OpenApiType.ResponseObject>> =
 // Maps the response content to a CodeGroupItem array.
 const mapToCodegroup = (content: Record<string, OpenApiType.MediaTypeObject>) => {
   return Object.entries(content).map(([responseType, item]) => {
-    // @TODO support component references here, too
+    let code = {};
+
+    if (item.schema) {
+      code = item.schema;
+    } else if (item.example) {
+      code = item.example;
+    } else if (item.examples) {
+      code = item.examples;
+    }
+
     return {
       title: responseType,
-      code: item.examples ?? item.examples ?? item.example,
+      code,
       language: responseType,
     };
   });

From 87bf5d6d0ea182b45cb82d4523b6861a442ef8d1 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Fri, 5 Apr 2024 18:01:17 +0200
Subject: [PATCH 11/41] feat(open-api): add basic display of open-api schemas

INT-407
---
 .../components/global/OpenApiResponses.vue    |  54 ++---
 .../components/global/OpenApiSchema.vue       | 196 ++++++++++++++++++
 2 files changed, 225 insertions(+), 25 deletions(-)
 create mode 100644 src/.vuepress/theme/client/components/global/OpenApiSchema.vue

diff --git a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
index e4a2fa6b..2e065077 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
@@ -8,10 +8,34 @@
         <Http :code="code" />
         <p v-if="response.description">{{ response.description }}</p>
 
-        <CodeGroup
-          v-if="response.content"
-          :items="mapToCodegroup(response.content)">
-        </CodeGroup>
+        <template v-for="(item, type) in response.content">
+          <OpenApiSchema
+            v-if="'schema' in item"
+            :key="`schema${type}`"
+            :schema="item.schema" />
+          <CodeGroup
+            v-else-if="'example' in item && item.example"
+            :key="`example${type}`"
+            :items="[
+              {
+                title: type,
+                code: JSON.stringify(item.example),
+                language: 'json',
+              },
+            ]">
+          </CodeGroup>
+          <CodeGroup
+            v-else-if="'examples' in item && Object.entries(item.examples)?.length"
+            :key="`examples${type}`"
+            :items="
+              Object.entries(item.examples).map(([key, value]) => ({
+                title: key,
+                code: JSON.stringify(value),
+                language: 'json',
+              }))
+            ">
+          </CodeGroup>
+        </template>
       </li>
     </ul>
   </div>
@@ -20,6 +44,7 @@
 <script setup lang="ts">
 import {computed, type ComputedRef} from 'vue';
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import OpenApiSchema from './OpenApiSchema.vue';
 import Http from './Http.vue';
 import CodeGroup from './CodeGroup.vue';
 
@@ -42,25 +67,4 @@ const responseObjects: ComputedRef<Record<string, OpenApiType.ResponseObject>> =
     });
   return objects;
 });
-
-// Maps the response content to a CodeGroupItem array.
-const mapToCodegroup = (content: Record<string, OpenApiType.MediaTypeObject>) => {
-  return Object.entries(content).map(([responseType, item]) => {
-    let code = {};
-
-    if (item.schema) {
-      code = item.schema;
-    } else if (item.example) {
-      code = item.example;
-    } else if (item.examples) {
-      code = item.examples;
-    }
-
-    return {
-      title: responseType,
-      code,
-      language: responseType,
-    };
-  });
-};
 </script>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSchema.vue b/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
new file mode 100644
index 00000000..37b6e077
--- /dev/null
+++ b/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
@@ -0,0 +1,196 @@
+<template>
+  <div
+    v-if="schema"
+    class="">
+    <strong
+      v-if="title"
+      class="items-center schema-row">
+      {{ title }}
+    </strong>
+    <strong v-else-if="schema.title">
+      {{ schema.title }}
+    </strong>
+    <p v-if="schema.description">
+      {{ schema.description }}
+    </p>
+    <div
+      v-if="schema.type"
+      class="items-center schema-row">
+      <span class="font-bold mr-2 schema-row-label">Type:</span>
+      <span class="schema-row-value">{{ schema.type }}</span>
+    </div>
+    <div
+      v-if="schema.format"
+      class="items-center schema-row">
+      <span class="font-bold mr-2 schema-row-label">Format:</span>
+      <span class="schema-row-value">{{ schema.format }}</span>
+    </div>
+    <div
+      v-if="schema.enum"
+      class="items-center schema-row">
+      <div class="font-bold mr-2 schema-row-label">Enum:</div>
+      <div class="p-2 schema-row-value">
+        <ul class="list-disc">
+          <li
+            v-for="(value, index) in schema.enum"
+            :key="index">
+            {{ value }}
+          </li>
+        </ul>
+      </div>
+    </div>
+    <div
+      v-if="schema.default"
+      class="items-center schema-row">
+      <span class="font-bold mr-2 schema-row-label">Default:</span>
+      <span class="schema-row-value">{{ schema.default }}</span>
+    </div>
+    <div
+      v-if="schema.pattern"
+      class="items-center schema-row">
+      <span class="font-bold mr-2 schema-row-label">Pattern:</span>
+      <span class="schema-row-value">{{ schema.pattern }}</span>
+    </div>
+    <div
+      v-if="schema.items"
+      class="items-center schema-row">
+      <div class="font-bold mr-2 schema-row-label">Items:</div>
+      <div class="schema-row-value">
+        <OpenApiSchema
+          :schema="schema.items"
+          title="Items" />
+      </div>
+    </div>
+    <div
+      v-if="schema.properties"
+      class="items-center schema-row">
+      <div class="font-bold mr-2 schema-row-label">Properties:</div>
+      <div class="schema-row-value">
+        <table
+          :open="open"
+          class="border-collapse border-spacing-0">
+          <thead class="bg-gray-100">
+            <th>Name</th>
+            <th>Type</th>
+            <th>Description</th>
+          </thead>
+          <tbody>
+            <tr
+              v-for="(property, key) in schema.properties"
+              :key="key"
+              :has-nested-table="hasNesting(key, property)">
+              <td class="align-top">{{ key }}</td>
+              <td class="align-top">
+                <pre class="m-0 p-0">{{ property.type }}</pre>
+              </td>
+              <td class="align-top">
+                <strong
+                  v-if="property.title"
+                  class="schema-row">
+                  {{ property.title }}
+                </strong>
+                <p
+                  v-if="property.description"
+                  class="schema-row">
+                  {{ property.description }}
+                </p>
+
+                <div v-if="key === 'reference'">
+                  <OpenApiSchema
+                    :schema="property"
+                    title="reference" />
+                </div>
+                <div
+                  v-if="property.items"
+                  class="px-2 py-2">
+                  <OpenApiSchema
+                    :schema="property.items"
+                    title="Items" />
+                </div>
+                <div
+                  v-if="property.properties"
+                  class="px-2 py-2">
+                  <OpenApiSchema :schema="{properties: property.properties}" />
+                </div>
+                <div
+                  v-if="property.allOf"
+                  class="px-2 py-2">
+                  <div
+                    v-for="(allOf, index) in property.allOf"
+                    :key="index">
+                    <OpenApiSchema :schema="allOf" />
+                  </div>
+                </div>
+                <div
+                  v-if="property.oneOf"
+                  class="items-center schema-row">
+                  <div class="font-bold mr-2 schema-row-label">One of:</div>
+                  <div class="schema-row-value">
+                    <div
+                      v-for="(oneOf, index) in property.oneOf"
+                      :key="index">
+                      <OpenApiSchema :schema="oneOf" />
+                    </div>
+                  </div>
+                </div>
+              </td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+    </div>
+    <div
+      v-if="schema.additionalProperties"
+      class="items-center schema-row">
+      <div class="schema-row-value">
+        <OpenApiSchema
+          :schema="schema.additionalProperties"
+          title="Additonal properties"
+          :open="false" />
+      </div>
+    </div>
+
+    <div
+      v-if="schema.allOf"
+      class="items-center schema-row">
+      <OpenApiSchema
+        :schema="assignAllOf(schema.allOf)"
+        :open="false" />
+    </div>
+
+    <div
+      v-if="schema.oneOf"
+      class="items-center schema-row">
+      <div class="font-bold mr-2 schema-row-label">One of</div>
+      <div class="schema-row-value">
+        <div
+          v-for="(oneOf, index) in schema.oneOf"
+          :key="index">
+          <OpenApiSchema
+            :schema="oneOf"
+            :open="false" />
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+  schema: object;
+  title?: string;
+  open?: boolean;
+}>();
+
+const assignAllOf = (allOf) => {
+  return {
+    properties: allOf.reduce((acc, curr) => {
+      return {...acc, ...curr.properties};
+    }, {}),
+  };
+};
+
+function hasNesting(key: string, property) {
+  return key === 'reference' || !!property.properties || !!property.items || !!property.oneOf || !!property.allOf;
+}
+</script>

From 7f7ed9b4906a4cae91f22db968e2e4519b38fa61 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Mon, 8 Apr 2024 16:13:50 +0200
Subject: [PATCH 12/41] feat(open-api): improve rendering of (response) schemas

INT-407
---
 .../components/global/OpenApiResponses.vue    |  65 ++--
 .../components/global/OpenApiSchema.vue       | 310 ++++++++----------
 .../components/global/OpenApiSchemaInfo.vue   |  60 ++++
 3 files changed, 240 insertions(+), 195 deletions(-)
 create mode 100644 src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue

diff --git a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
index 2e065077..6a2ea9a0 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
@@ -9,32 +9,45 @@
         <p v-if="response.description">{{ response.description }}</p>
 
         <template v-for="(item, type) in response.content">
-          <OpenApiSchema
-            v-if="'schema' in item"
-            :key="`schema${type}`"
-            :schema="item.schema" />
-          <CodeGroup
-            v-else-if="'example' in item && item.example"
-            :key="`example${type}`"
-            :items="[
-              {
-                title: type,
-                code: JSON.stringify(item.example),
-                language: 'json',
-              },
-            ]">
-          </CodeGroup>
-          <CodeGroup
-            v-else-if="'examples' in item && Object.entries(item.examples)?.length"
-            :key="`examples${type}`"
-            :items="
-              Object.entries(item.examples).map(([key, value]) => ({
-                title: key,
-                code: JSON.stringify(value),
-                language: 'json',
-              }))
-            ">
-          </CodeGroup>
+          <section
+            v-if="'schema' in item && !!item.schema"
+            :key="`schema${type}`">
+            <h5>Schema</h5>
+            <OpenApiSchema
+              :title="type.toString()"
+              :schema="item.schema" />
+          </section>
+
+          <section
+            v-if="'example' in item && item.example"
+            :key="`example${type}`">
+            <h5>Example</h5>
+            <CodeGroup
+              :items="[
+                {
+                  title: type.toString(),
+                  code: JSON.stringify(item.example),
+                  language: 'json',
+                },
+              ]">
+            </CodeGroup>
+          </section>
+
+          <section
+            v-if="'examples' in item && item.examples"
+            :key="`examples${type}`">
+            <h5>Examples</h5>
+            <CodeGroup
+              v-if="'examples' in item && Object.entries(item.examples)?.length"
+              :items="
+                Object.entries(item.examples).map(([key, value]) => ({
+                  title: key,
+                  code: JSON.stringify(value),
+                  language: 'json',
+                }))
+              ">
+            </CodeGroup>
+          </section>
         </template>
       </li>
     </ul>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSchema.vue b/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
index 37b6e077..c8e5216e 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
@@ -1,196 +1,168 @@
 <template>
   <div
     v-if="schema"
-    class="">
-    <strong
-      v-if="title"
-      class="items-center schema-row">
-      {{ title }}
-    </strong>
-    <strong v-else-if="schema.title">
-      {{ schema.title }}
-    </strong>
-    <p v-if="schema.description">
-      {{ schema.description }}
-    </p>
-    <div
-      v-if="schema.type"
-      class="items-center schema-row">
-      <span class="font-bold mr-2 schema-row-label">Type:</span>
-      <span class="schema-row-value">{{ schema.type }}</span>
-    </div>
-    <div
-      v-if="schema.format"
-      class="items-center schema-row">
-      <span class="font-bold mr-2 schema-row-label">Format:</span>
-      <span class="schema-row-value">{{ schema.format }}</span>
-    </div>
-    <div
-      v-if="schema.enum"
-      class="items-center schema-row">
-      <div class="font-bold mr-2 schema-row-label">Enum:</div>
-      <div class="p-2 schema-row-value">
-        <ul class="list-disc">
-          <li
-            v-for="(value, index) in schema.enum"
-            :key="index">
-            {{ value }}
-          </li>
-        </ul>
-      </div>
-    </div>
-    <div
-      v-if="schema.default"
-      class="items-center schema-row">
-      <span class="font-bold mr-2 schema-row-label">Default:</span>
-      <span class="schema-row-value">{{ schema.default }}</span>
-    </div>
-    <div
-      v-if="schema.pattern"
-      class="items-center schema-row">
-      <span class="font-bold mr-2 schema-row-label">Pattern:</span>
-      <span class="schema-row-value">{{ schema.pattern }}</span>
-    </div>
-    <div
-      v-if="schema.items"
-      class="items-center schema-row">
-      <div class="font-bold mr-2 schema-row-label">Items:</div>
-      <div class="schema-row-value">
-        <OpenApiSchema
-          :schema="schema.items"
-          title="Items" />
-      </div>
-    </div>
-    <div
-      v-if="schema.properties"
-      class="items-center schema-row">
-      <div class="font-bold mr-2 schema-row-label">Properties:</div>
-      <div class="schema-row-value">
-        <table
-          :open="open"
-          class="border-collapse border-spacing-0">
-          <thead class="bg-gray-100">
-            <th>Name</th>
-            <th>Type</th>
-            <th>Description</th>
-          </thead>
-          <tbody>
-            <tr
-              v-for="(property, key) in schema.properties"
-              :key="key"
-              :has-nested-table="hasNesting(key, property)">
-              <td class="align-top">{{ key }}</td>
-              <td class="align-top">
-                <pre class="m-0 p-0">{{ property.type }}</pre>
-              </td>
-              <td class="align-top">
-                <strong
-                  v-if="property.title"
-                  class="schema-row">
-                  {{ property.title }}
-                </strong>
-                <p
-                  v-if="property.description"
-                  class="schema-row">
-                  {{ property.description }}
-                </p>
-
-                <div v-if="key === 'reference'">
-                  <OpenApiSchema
-                    :schema="property"
-                    title="reference" />
-                </div>
-                <div
-                  v-if="property.items"
-                  class="px-2 py-2">
-                  <OpenApiSchema
-                    :schema="property.items"
-                    title="Items" />
-                </div>
-                <div
-                  v-if="property.properties"
-                  class="px-2 py-2">
-                  <OpenApiSchema :schema="{properties: property.properties}" />
-                </div>
-                <div
-                  v-if="property.allOf"
-                  class="px-2 py-2">
-                  <div
-                    v-for="(allOf, index) in property.allOf"
-                    :key="index">
-                    <OpenApiSchema :schema="allOf" />
-                  </div>
-                </div>
-                <div
-                  v-if="property.oneOf"
-                  class="items-center schema-row">
-                  <div class="font-bold mr-2 schema-row-label">One of:</div>
-                  <div class="schema-row-value">
-                    <div
-                      v-for="(oneOf, index) in property.oneOf"
-                      :key="index">
-                      <OpenApiSchema :schema="oneOf" />
-                    </div>
-                  </div>
-                </div>
-              </td>
-            </tr>
-          </tbody>
-        </table>
-      </div>
+    class="mb-4">
+    <OpenApiSchemaInfo
+      :schema="schema"
+      :title="title" />
+
+    <div v-if="isArraySchemaObject(schema) && schema.items">
+      <OpenApiSchema
+        :schema="schema.items"
+        title="Items" />
     </div>
-    <div
-      v-if="schema.additionalProperties"
-      class="items-center schema-row">
-      <div class="schema-row-value">
+
+    <table
+      v-if="isSchemaObject(schema) && schema.properties"
+      class="bg-gray-50 border-collapse border-spacing-0 table-auto">
+      <thead class="bg-gray-200">
+        <th>Name</th>
+        <th v-if="anyPropertyHasNesting(schema.properties)">Content</th>
+      </thead>
+      <tbody>
+        <tr
+          v-for="(property, key) in schema.properties"
+          :key="key"
+          :has-nested-table="propertyHasNesting(key, Object.keys(property))">
+          <td class="align-top">
+            <OpenApiSchemaInfo
+              :schema="property"
+              :is-required="schema.required?.includes(key.toString())"
+              :title="key.toString()" />
+          </td>
+
+          <td
+            v-if="isSchemaObject(property) && propertyHasNesting(key, Object.keys(property))"
+            class="align-top">
+            <a
+              v-if="collapsible"
+              href="#"
+              class="inline-flex items-center no-link-styles text-goldfish-500 text-sm"
+              @click.prevent="showNested = !showNested">
+              <template v-if="showNested">
+                <span>Hide content</span>
+                <i class="align-middle flex-1 icon-chevron-left inline-flex" />
+              </template>
+              <template v-else><span>Show content</span> <i class="align-middle icon-chevron-right" /></template>
+            </a>
+
+            <div
+              v-if="isArraySchemaObject(property) && property.items"
+              class="px-2 py-2">
+              <OpenApiSchema
+                v-show="!collapsible || (collapsible && showNested)"
+                :schema="property.items"
+                :collapsible="true" />
+            </div>
+
+            <div
+              v-if="property.properties"
+              class="px-2 py-2">
+              <OpenApiSchema
+                v-show="!collapsible || (collapsible && showNested)"
+                :schema="{properties: property.properties}"
+                :collapsible="true" />
+            </div>
+
+            <div
+              v-if="property.allOf"
+              class="px-2 py-2">
+              <strong>All of:</strong>
+              <div
+                v-for="(allOf, index) in property.allOf"
+                :key="index">
+                <OpenApiSchema
+                  v-show="!collapsible || (collapsible && showNested)"
+                  :schema="allOf"
+                  :collapsible="true" />
+              </div>
+            </div>
+
+            <div
+              v-if="property.oneOf"
+              class="px-2 py-2">
+              <strong>One of:</strong>
+              <div
+                v-for="(oneOf, index) in property.oneOf"
+                :key="index">
+                <OpenApiSchema
+                  v-show="!collapsible || (collapsible && showNested)"
+                  :schema="oneOf"
+                  :collapsible="true" />
+              </div>
+            </div>
+          </td>
+        </tr>
+      </tbody>
+    </table>
+
+    <template v-if="isSchemaObject(schema)">
+      <div v-if="schema.additionalProperties && schema.additionalProperties !== true">
         <OpenApiSchema
           :schema="schema.additionalProperties"
-          title="Additonal properties"
-          :open="false" />
+          title="Additonal properties" />
       </div>
-    </div>
 
-    <div
-      v-if="schema.allOf"
-      class="items-center schema-row">
-      <OpenApiSchema
-        :schema="assignAllOf(schema.allOf)"
-        :open="false" />
-    </div>
+      <div v-if="schema.allOf">
+        <strong>All of:</strong>
+        <div
+          v-for="(oneOf, index) in schema.allOf"
+          :key="index"
+          class="ml-3">
+          <OpenApiSchema
+            :schema="oneOf"
+            :collapsible="false" />
+        </div>
+      </div>
 
-    <div
-      v-if="schema.oneOf"
-      class="items-center schema-row">
-      <div class="font-bold mr-2 schema-row-label">One of</div>
-      <div class="schema-row-value">
+      <div v-if="schema.oneOf">
+        <strong>One of:</strong>
         <div
           v-for="(oneOf, index) in schema.oneOf"
-          :key="index">
+          :key="index"
+          class="ml-3">
           <OpenApiSchema
             :schema="oneOf"
-            :open="false" />
+            :collapsible="false" />
         </div>
       </div>
-    </div>
+    </template>
   </div>
 </template>
 
 <script setup lang="ts">
+import {ref} from 'vue';
+import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import OpenApiSchemaInfo from './OpenApiSchemaInfo.vue';
+
 defineProps<{
-  schema: object;
+  schema: OpenApiType.SchemaObject | OpenApiType.ReferenceObject;
   title?: string;
-  open?: boolean;
+  collapsible?: boolean;
 }>();
 
-const assignAllOf = (allOf) => {
-  return {
-    properties: allOf.reduce((acc, curr) => {
-      return {...acc, ...curr.properties};
-    }, {}),
-  };
+const showNested = ref(false);
+
+// Guard to check if the schema is an OpenApiType.SchemaObject.
+const isSchemaObject = (schema: object): schema is OpenApiType.SchemaObject => {
+  return typeof schema === 'object';
 };
 
-function hasNesting(key: string, property) {
-  return key === 'reference' || !!property.properties || !!property.items || !!property.oneOf || !!property.allOf;
+// Guard to check if the schema is an OpenApiType.ArraySchemaObject.
+const isArraySchemaObject = (schema: object): schema is OpenApiType.ArraySchemaObject => {
+  return typeof schema === 'object' && 'items' in schema;
+};
+
+function anyPropertyHasNesting(properties: OpenApiType.SchemaObject['properties']) {
+  return properties
+    ? Object.keys(properties).some((key) => propertyHasNesting(key, Object.keys(properties[key])))
+    : false;
+}
+
+function propertyHasNesting(key: string | number, children: string[]) {
+  return (
+    key === 'reference' ||
+    ['properties', 'items', 'oneOf', 'allOf'].some((propertyName) => children.includes(propertyName))
+  );
 }
 </script>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
new file mode 100644
index 00000000..3169373e
--- /dev/null
+++ b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
@@ -0,0 +1,60 @@
+<template>
+  <header>
+    <strong v-if="title">{{ title }}</strong>
+    <strong v-else-if="schema && schema.title">{{ schema.title }}</strong>
+    <span
+      v-if="isRequired"
+      title="Required"
+      class="text-red-600"
+      >*</span
+    >
+    <pre
+      v-if="schema && schema.type"
+      class="m-0 p-0 text-sm whitespace-nowrap">
+          {{ schema.type }}
+          <template v-if="schema.format">({{ schema.format }})</template>
+      </pre>
+
+    <p
+      v-if="schema && schema.description"
+      class="m-0 p-0 text-gray-500 text-sm">
+      {{ schema.description }}
+    </p>
+
+    <template v-if="schema && schema.enum">
+      <strong class="text-sm">Enum:</strong>
+      <ul class="list-disc">
+        <li
+          v-for="(value, index) in schema.enum"
+          :key="index">
+          {{ value }}
+        </li>
+      </ul>
+    </template>
+
+    <template v-if="schema && schema.default">
+      <strong class="inline-block text-sm">Default:</strong>&nbsp;
+      <pre class="inline-block m-0 p-0 text-sm">{{ schema.default }}</pre>
+    </template>
+
+    <template v-if="schema && schema.pattern">
+      <strong class="inline-block text-sm">Pattern:</strong>&nbsp;
+      <pre class="inline-block m-0 p-0 text-sm">{{ schema.pattern }}</pre>
+    </template>
+
+    <template v-if="schema.example">
+      <strong class="inline-block text-sm">Example:</strong>&nbsp;
+      <pre class="inline-block m-0 p-0 text-sm">{{ schema.example }}</pre>
+    </template>
+  </header>
+</template>
+
+<script setup lang="ts">
+import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+
+defineProps<{
+  title?: string;
+  schema: OpenApiType.SchemaObject;
+  isRequired?: boolean;
+}>();
+</script>

From 57b161f3a4373fef8891070651e9d6d29d84d811 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Tue, 9 Apr 2024 12:52:59 +0200
Subject: [PATCH 13/41] feat(open-api): add display of request parameter and
 body information

INT-407
---
 .../client/components/global/OpenApiPath.vue  |  28 +++-
 .../components/global/OpenApiRequestParam.vue | 131 ++++++++++++++++++
 .../components/global/OpenApiSchema.vue       |   4 +-
 .../components/global/OpenApiSchemaInfo.vue   |   6 +-
 4 files changed, 162 insertions(+), 7 deletions(-)
 create mode 100644 src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue

diff --git a/src/.vuepress/theme/client/components/global/OpenApiPath.vue b/src/.vuepress/theme/client/components/global/OpenApiPath.vue
index 4760625d..8d3209d0 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiPath.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiPath.vue
@@ -17,7 +17,26 @@
 
         <p v-if="'description' in operation">{{ operation.description }}</p>
 
-        <!-- TODO: Parameters table -->
+        <template v-if="'parameters' in operation">
+          <h4>Request parameters</h4>
+          <table>
+            <thead>
+              <th>Parameter</th>
+              <th>Info</th>
+            </thead>
+            <tr
+              v-for="(parameter, index) in operation.parameters"
+              :key="index">
+              <OpenApiRequestParam
+                v-if="isParameterType(parameter)"
+                :parameter="parameter" />
+            </tr>
+          </table>
+        </template>
+        <template v-if="'requestBody' in operation">
+          <h4>Request body</h4>
+          {{ operation.requestBody }}</template
+        >
 
         <OpenApiResponses
           v-if="'responses' in operation"
@@ -30,10 +49,17 @@
 <script setup lang="ts">
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
 import OpenApiResponses from './OpenApiResponses.vue';
+import OpenApiRequestParam from './OpenApiRequestParam.vue';
 import OpenApiOperation from './OpenApiOperation.vue';
 
 defineProps<{
   title: string;
   path: OpenApiType.PathItemObject;
 }>();
+
+function isParameterType(
+  parameter: OpenApiType.ParameterObject | OpenApiType.ReferenceObject,
+): parameter is OpenApiType.ParameterObject {
+  return 'in' in parameter && 'schema' in parameter;
+}
 </script>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue b/src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue
new file mode 100644
index 00000000..11e1bef2
--- /dev/null
+++ b/src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue
@@ -0,0 +1,131 @@
+<template>
+  <td>
+    <template v-if="parameter.name">
+      <strong>{{ parameter.name }}</strong>
+      <span
+        v-if="parameter.required"
+        class="text-red-500"
+        title="Required">
+        *
+      </span>
+      <span
+        v-for="flag in flags"
+        :key="flag"
+        >{{ flag }}</span
+      >
+    </template>
+
+    <OpenApiSchema
+      v-if="parameter.schema"
+      :schema="parameter.schema" />
+
+    <div
+      v-if="
+        parameter.description &&
+        !(parameter.schema && 'description' in parameter.schema && parameter.schema.description?.length)
+      "
+      class="text-gray-500 text-sm"
+      v-html="parameter.description" />
+  </td>
+
+  <td>
+    <div
+      v-if="parameter.in"
+      class="oapi-res-param__param">
+      In: <code>{{ parameter.in }}</code>
+    </div>
+
+    <div
+      v-if="parameter.style"
+      class="oapi-res-param__param">
+      Style: <code>{{ parameter.style }}</code>
+    </div>
+
+    <!-- TODO use / create examples component! -->
+
+    <div
+      v-if="parameter.example"
+      class="oapi-res-param__param">
+      Example: <br v-if="exampleString.includes('\n')" /><code v-html="exampleString" />
+    </div>
+    <div
+      v-if="parameter.examples"
+      class="oapi-res-param__examples">
+      <div class="oapi-res-param__muted">Examples:</div>
+      <div
+        v-for="(example, exampleName) in parameter.examples"
+        :key="exampleName"
+        class="oapi-res-param-example">
+        <div class="oapi-res-param-example__name">
+          {{ exampleName }}
+        </div>
+        <div
+          v-if="example.summary"
+          class="oapi-res-param-example__summary">
+          {{ example.summary }}
+        </div>
+        <div
+          v-if="example.description"
+          class="oapi-res-param-example__description"
+          v-html="example.description" />
+        <div
+          v-if="example.value"
+          class="oapi-res-param-example__value">
+          <pre v-html="JSON.stringify(example.value, null, 2)" />
+        </div>
+      </div>
+    </div>
+
+    <div
+      v-if="parameter.content"
+      class="oapi-res-param__content">
+      <div class="oapi-res-param__muted">Content:</div>
+      TODO : MEDIA TYPES
+      <!--
+        <OpenApiMediaTypes
+        :current-locale="currentLocale"
+        :data="parameter.content" />
+      -->
+    </div>
+  </td>
+</template>
+
+<script setup lang="ts">
+import {computed, defineProps} from 'vue';
+import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import OpenApiSchema from './OpenApiSchema.vue';
+// import OpenApiObjectModel from './OpenApiObjectModel.vue';
+// import OpenApiMediaTypes from './OpenApiMediaTypes.vue';
+
+const props = defineProps<{
+  parameter: OpenApiType.ParameterObject;
+}>();
+
+const flags = computed(() => {
+  const arr: string[] = [];
+
+  if (props.parameter.deprecated) {
+    arr.push('Deprecated');
+  }
+
+  if (props.parameter.allowEmptyValue) {
+    arr.push('Allow empty');
+  }
+
+  if (props.parameter.allowReserved) {
+    arr.push('Allow reserved');
+  }
+
+  return arr;
+});
+
+const exampleString = computed(() => {
+  const spacing = 2;
+
+  if (!props.parameter.example) return '';
+
+  if (typeof props.parameter.example === 'object') return JSON.stringify(props.parameter.example, null, spacing);
+
+  return props.parameter.example.toString();
+});
+</script>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSchema.vue b/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
index c8e5216e..6f279b62 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
@@ -1,7 +1,5 @@
 <template>
-  <div
-    v-if="schema"
-    class="mb-4">
+  <div v-if="schema">
     <OpenApiSchemaInfo
       :schema="schema"
       :title="title" />
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
index 3169373e..f42fdd86 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
@@ -34,17 +34,17 @@
 
     <template v-if="schema && schema.default">
       <strong class="inline-block text-sm">Default:</strong>&nbsp;
-      <pre class="inline-block m-0 p-0 text-sm">{{ schema.default }}</pre>
+      <code class="inline-block m-0 p-1 text-sm">{{ schema.default }}</code>
     </template>
 
     <template v-if="schema && schema.pattern">
       <strong class="inline-block text-sm">Pattern:</strong>&nbsp;
-      <pre class="inline-block m-0 p-0 text-sm">{{ schema.pattern }}</pre>
+      <code class="inline-block m-0 p-1 text-sm">{{ schema.pattern }}</code>
     </template>
 
     <template v-if="schema.example">
       <strong class="inline-block text-sm">Example:</strong>&nbsp;
-      <pre class="inline-block m-0 p-0 text-sm">{{ schema.example }}</pre>
+      <code class="inline-block m-0 p-1 text-sm">{{ schema.example }}</code>
     </template>
   </header>
 </template>

From f00469ca0138240e856ed4796a1f77fca4d7946b Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Wed, 10 Apr 2024 10:52:45 +0200
Subject: [PATCH 14/41] feat(open-api): add consistent rendering of examples in
 request- and response tables

INT-407
---
 .../components/global/OpenApiExample.vue      | 64 +++++++++++++++++
 .../client/components/global/OpenApiPath.vue  |  3 +-
 .../components/global/OpenApiRequestParam.vue | 68 +++++--------------
 .../components/global/OpenApiSchemaInfo.vue   |  4 +-
 4 files changed, 86 insertions(+), 53 deletions(-)
 create mode 100644 src/.vuepress/theme/client/components/global/OpenApiExample.vue

diff --git a/src/.vuepress/theme/client/components/global/OpenApiExample.vue b/src/.vuepress/theme/client/components/global/OpenApiExample.vue
new file mode 100644
index 00000000..36e40aa2
--- /dev/null
+++ b/src/.vuepress/theme/client/components/global/OpenApiExample.vue
@@ -0,0 +1,64 @@
+<template>
+  <template v-if="example">
+    <strong class="inline-block text-sm">{{ title || 'Example' }}:</strong>&nbsp;
+    <p
+      v-if="isExampleObject(example) && example.summary"
+      class="text-sm">
+      {{ example.summary }}
+    </p>
+
+    <div
+      v-if="isExampleObject(example) && example.description"
+      class="text-sm"
+      v-html="example.description" />
+
+    <template v-if="formattedExample">
+      <CodeBlock
+        v-if="isMultilineString"
+        :code="formattedExample"
+        language="json" />
+      <code
+        v-else
+        class="inline-block m-0 p-1 text-sm"
+        >{{ formattedExample }}</code
+      >
+    </template>
+  </template>
+</template>
+
+<script setup lang="ts">
+import {computed} from 'vue';
+import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import CodeBlock from './CodeBlock.vue';
+
+const props = defineProps<{
+  title?: string;
+  example?: OpenApiType.ExampleObject | unknown;
+}>();
+
+const formattedExample = computed(() => {
+  if (!props.example) return undefined;
+
+  if (isExampleObject(props.example)) return formatExample(props.example.value);
+
+  if (typeof props.example === 'object') return formatExample(props.example);
+
+  return props.example.toString();
+});
+
+// Check the formattedExample for linebreaks, if it has those, it's a multiline string
+const isMultilineString = computed(() => formattedExample.value?.includes('\n'));
+
+function formatExample(example: unknown): string {
+  const spacing = 2;
+
+  return JSON.stringify(example, null, spacing);
+}
+
+// Guard to check if example is an Example object
+const isExampleObject = (example: unknown): example is OpenApiType.ExampleObject => {
+  return (
+    !!example && typeof example === 'object' && 'summary' in example && 'description' in example && 'value' in example
+  );
+};
+</script>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiPath.vue b/src/.vuepress/theme/client/components/global/OpenApiPath.vue
index 8d3209d0..abeffe0b 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiPath.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiPath.vue
@@ -22,7 +22,8 @@
           <table>
             <thead>
               <th>Parameter</th>
-              <th>Info</th>
+              <th>Location</th>
+              <th>Information</th>
             </thead>
             <tr
               v-for="(parameter, index) in operation.parameters"
diff --git a/src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue b/src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue
index 11e1bef2..7f85105f 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue
@@ -26,56 +26,33 @@
       "
       class="text-gray-500 text-sm"
       v-html="parameter.description" />
+
+    <!-- TODO use / create examples component! -->
+    <OpenApiExample
+      v-if="parameter.example"
+      :example="parameter.example" />
+    <div v-if="parameter.examples">
+      <strong>Examples:</strong>
+      <OpenApiExample
+        v-for="(example, exampleName) in parameter.examples"
+        :key="exampleName"
+        :title="exampleName.toString()"
+        :example="example">
+      </OpenApiExample>
+    </div>
   </td>
 
   <td>
-    <div
-      v-if="parameter.in"
-      class="oapi-res-param__param">
-      In: <code>{{ parameter.in }}</code>
-    </div>
+    <code>{{ parameter.in }}</code>
+  </td>
 
+  <td>
     <div
       v-if="parameter.style"
       class="oapi-res-param__param">
       Style: <code>{{ parameter.style }}</code>
     </div>
 
-    <!-- TODO use / create examples component! -->
-
-    <div
-      v-if="parameter.example"
-      class="oapi-res-param__param">
-      Example: <br v-if="exampleString.includes('\n')" /><code v-html="exampleString" />
-    </div>
-    <div
-      v-if="parameter.examples"
-      class="oapi-res-param__examples">
-      <div class="oapi-res-param__muted">Examples:</div>
-      <div
-        v-for="(example, exampleName) in parameter.examples"
-        :key="exampleName"
-        class="oapi-res-param-example">
-        <div class="oapi-res-param-example__name">
-          {{ exampleName }}
-        </div>
-        <div
-          v-if="example.summary"
-          class="oapi-res-param-example__summary">
-          {{ example.summary }}
-        </div>
-        <div
-          v-if="example.description"
-          class="oapi-res-param-example__description"
-          v-html="example.description" />
-        <div
-          v-if="example.value"
-          class="oapi-res-param-example__value">
-          <pre v-html="JSON.stringify(example.value, null, 2)" />
-        </div>
-      </div>
-    </div>
-
     <div
       v-if="parameter.content"
       class="oapi-res-param__content">
@@ -96,6 +73,7 @@ import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
 import OpenApiSchema from './OpenApiSchema.vue';
 // import OpenApiObjectModel from './OpenApiObjectModel.vue';
 // import OpenApiMediaTypes from './OpenApiMediaTypes.vue';
+import OpenApiExample from './OpenApiExample.vue';
 
 const props = defineProps<{
   parameter: OpenApiType.ParameterObject;
@@ -118,14 +96,4 @@ const flags = computed(() => {
 
   return arr;
 });
-
-const exampleString = computed(() => {
-  const spacing = 2;
-
-  if (!props.parameter.example) return '';
-
-  if (typeof props.parameter.example === 'object') return JSON.stringify(props.parameter.example, null, spacing);
-
-  return props.parameter.example.toString();
-});
 </script>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
index f42fdd86..a02deb5a 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
@@ -43,14 +43,14 @@
     </template>
 
     <template v-if="schema.example">
-      <strong class="inline-block text-sm">Example:</strong>&nbsp;
-      <code class="inline-block m-0 p-1 text-sm">{{ schema.example }}</code>
+      <OpenApiExample :example="schema.example" />
     </template>
   </header>
 </template>
 
 <script setup lang="ts">
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import OpenApiExample from './OpenApiExample.vue';
 
 defineProps<{
   title?: string;

From f200a81234a17c52326fdb67ab051080f98a0d3d Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Wed, 10 Apr 2024 11:46:39 +0200
Subject: [PATCH 15/41] feat(open-api): add support for rendering request body
 description and schema

INT-407
---
 .../client/components/global/OpenApiPath.vue  | 23 ++++++++++++++++---
 src/api-reference/9999.test.md                |  6 ++++-
 2 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/src/.vuepress/theme/client/components/global/OpenApiPath.vue b/src/.vuepress/theme/client/components/global/OpenApiPath.vue
index abeffe0b..d2c0c94b 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiPath.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiPath.vue
@@ -34,10 +34,24 @@
             </tr>
           </table>
         </template>
-        <template v-if="'requestBody' in operation">
+        <template v-if="'requestBody' in operation && operation.requestBody">
           <h4>Request body</h4>
-          {{ operation.requestBody }}</template
-        >
+
+          <template v-if="operation.requestBody?.description">
+            <Markdown :content="operation.requestBody?.description"></Markdown>
+          </template>
+          <DetailsExpand
+            v-if="'content' in operation.requestBody && operation.requestBody.content"
+            tag="h5"
+            title="Schema">
+            <div
+              v-for="(content, key) in operation.requestBody.content"
+              :key="key">
+              <strong>{{ key }}</strong>
+              <OpenApiSchema :schema="content?.schema" />
+            </div>
+          </DetailsExpand>
+        </template>
 
         <OpenApiResponses
           v-if="'responses' in operation"
@@ -49,9 +63,12 @@
 
 <script setup lang="ts">
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import OpenApiSchema from './OpenApiSchema.vue';
 import OpenApiResponses from './OpenApiResponses.vue';
 import OpenApiRequestParam from './OpenApiRequestParam.vue';
 import OpenApiOperation from './OpenApiOperation.vue';
+import Markdown from './Markdown.vue';
+import DetailsExpand from './DetailsExpand.vue';
 
 defineProps<{
   title: string;
diff --git a/src/api-reference/9999.test.md b/src/api-reference/9999.test.md
index 146991ac..5f538979 100644
--- a/src/api-reference/9999.test.md
+++ b/src/api-reference/9999.test.md
@@ -64,7 +64,11 @@ title: 9999. Test
         operationId: 'postSubscriptions',
         parameters: [{ $ref: '#/components/parameters/user_agent_header' }],
         requestBody: {
-          description: '|\n            | **Hook** | **Description** |\n            |---- |------------|\n            | ```shipment_status_change``` | Whenever the shipment_status of a shipment changes, this webhook will send you an update with the new value. We will not send an update with a status.|\n            | ```shipment_label_created``` | When a label is created asynchronously (for example when creating shipments using accept header ```application/vnd.shipment_label+json;charset=utf-8```), this webhook will send you a message with the URL of the label. |\n            | ```order_status_change``` | Whenever the order_status of an order changes, this webhook will send you an update with the new value. |',
+          description: `| **Hook** | **Description** |
+|---- |------------|
+| \`shipment_status_change\` | Whenever the shipment_status of a shipment changes, this webhook will send you an update with the new value. We will not send an update with a status.|
+| \`shipment_label_created\` | When a label is created asynchronously (for example when creating shipments using accept header \`application/vnd.shipment_label+json;charset=utf-8\`), this webhook will send you a message with the URL of the label. |
+| \`order_status_change\` | Whenever the order_status of an order changes, this webhook will send you an update with the new value. |`,
           required: true,
           content: {
             'application/json; charset: utf-8': {

From 996d59d1af6b0cc6e85eb6a01ca2aa3469910b1c Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Wed, 10 Apr 2024 12:30:42 +0200
Subject: [PATCH 16/41] feat(open-api): wrap reponse examples and schemas in
 details/expand blocks

INT-407
---
 .../components/global/OpenApiResponses.vue    | 39 ++++++++++++-------
 1 file changed, 24 insertions(+), 15 deletions(-)

diff --git a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
index 6a2ea9a0..a0bf47c0 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
@@ -1,27 +1,34 @@
 <template>
   <div v-if="Object.entries(responseObjects)?.length">
     <h4>Responses</h4>
-    <ul>
+    <ul class="m-0 p-0">
       <li
         v-for="(response, code) in responseObjects"
-        :key="code">
+        :key="code"
+        class="m-0 p-0">
         <Http :code="code" />
-        <p v-if="response.description">{{ response.description }}</p>
+        <p
+          v-if="response.description"
+          class="text-gray-500 text-sm">
+          {{ response.description }}
+        </p>
 
         <template v-for="(item, type) in response.content">
-          <section
+          <DetailsExpand
             v-if="'schema' in item && !!item.schema"
-            :key="`schema${type}`">
-            <h5>Schema</h5>
+            :key="`schema${type}`"
+            title="Schema"
+            tag="strong">
             <OpenApiSchema
               :title="type.toString()"
               :schema="item.schema" />
-          </section>
+          </DetailsExpand>
 
-          <section
+          <DetailsExpand
             v-if="'example' in item && item.example"
-            :key="`example${type}`">
-            <h5>Example</h5>
+            :key="`example${type}`"
+            title="Example response"
+            tag="strong">
             <CodeGroup
               :items="[
                 {
@@ -31,12 +38,13 @@
                 },
               ]">
             </CodeGroup>
-          </section>
+          </DetailsExpand>
 
-          <section
+          <DetailsExpand
             v-if="'examples' in item && item.examples"
-            :key="`examples${type}`">
-            <h5>Examples</h5>
+            :key="`examples${type}`"
+            title="Example responses"
+            tag="strong">
             <CodeGroup
               v-if="'examples' in item && Object.entries(item.examples)?.length"
               :items="
@@ -47,7 +55,7 @@
                 }))
               ">
             </CodeGroup>
-          </section>
+          </DetailsExpand>
         </template>
       </li>
     </ul>
@@ -59,6 +67,7 @@ import {computed, type ComputedRef} from 'vue';
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
 import OpenApiSchema from './OpenApiSchema.vue';
 import Http from './Http.vue';
+import DetailsExpand from './DetailsExpand.vue';
 import CodeGroup from './CodeGroup.vue';
 
 const props = defineProps<{

From 3ede3d02b045739999cccfe551391f6ec89db398 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Wed, 10 Apr 2024 12:59:58 +0200
Subject: [PATCH 17/41] refactor(open-api): resolve type safety issues and
 create util file for OpenAPI type guards

INT-407
---
 .../client/components/global/OpenApi.vue      | 38 ++++++++++++-------
 .../client/components/global/OpenApiPath.vue  | 11 ++----
 .../components/global/OpenApiResponses.vue    |  6 +--
 .../components/global/OpenApiSchema.vue       | 11 +-----
 .../theme/client/utils/openApiGuards.ts       | 22 +++++++++++
 5 files changed, 53 insertions(+), 35 deletions(-)
 create mode 100644 src/.vuepress/theme/client/utils/openApiGuards.ts

diff --git a/src/.vuepress/theme/client/components/global/OpenApi.vue b/src/.vuepress/theme/client/components/global/OpenApi.vue
index fed8f5a5..0eb6c491 100644
--- a/src/.vuepress/theme/client/components/global/OpenApi.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApi.vue
@@ -27,22 +27,34 @@ const props = defineProps<{
 const resolvedDocument = computed(() => resolveRefs(props.document));
 
 // Recursively loop through the entire document and replace any $ref keys with their corresponding values
+type RecursiveType = {
+  [key: string]: unknown | RecursiveType | RecursiveType[];
+};
+
 function resolveRefs(document: OpenApiType.Document): OpenApiType.Document {
   const resolvedDocument = {...document};
 
-  function resolveRefsRecursive(obj: object | (string | number | object)[]) {
-    for (const key in obj) {
-      if (key === '$ref') {
-        const lookup = (obj as {$ref: string})[key];
-        // Lookup is a string that defines the path to the referenced object like '#/components/schemas/Example'
-        const path = lookup.split('/').slice(1);
-        // Find the referenced object in the document using lodash's get function
-        const referencedObject = get(resolvedDocument, path);
-        // Remove the $ref: '...' key from the object and replace it with the referenced object itself
-        obj = Object.assign(obj, referencedObject);
-      } else if (typeof obj[key] === 'object' || Array.isArray(obj[key])) {
-        // If the value is an object or an array, recursively call this function
-        resolveRefsRecursive(obj[key]);
+  function resolveRefsRecursive(obj: RecursiveType) {
+    if (Array.isArray(obj)) {
+      for (const item of obj) {
+        resolveRefsRecursive(item);
+      }
+    } else if (typeof obj === 'object') {
+      for (const key in obj) {
+        if (key === '$ref') {
+          const lookup = obj[key] as string;
+          // Lookup is a string that defines the path to the referenced object like '#/components/schemas/Example'
+          const path = lookup.split('/').slice(1);
+          // Find the referenced object in the document using lodash's get function
+          const referencedObject = get(resolvedDocument, path);
+
+          // Remove the $ref: '...' key from the object and replace it with the referenced object itself
+          obj = Object.assign(obj, referencedObject);
+        } else if (typeof obj[key] === 'object' || Array.isArray(obj[key])) {
+          const guarded = obj[key] as RecursiveType;
+          // If the value is an object or an array, recursively call this function
+          resolveRefsRecursive(guarded);
+        }
       }
     }
   }
diff --git a/src/.vuepress/theme/client/components/global/OpenApiPath.vue b/src/.vuepress/theme/client/components/global/OpenApiPath.vue
index d2c0c94b..4c1548a1 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiPath.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiPath.vue
@@ -48,7 +48,9 @@
               v-for="(content, key) in operation.requestBody.content"
               :key="key">
               <strong>{{ key }}</strong>
-              <OpenApiSchema :schema="content?.schema" />
+              <OpenApiSchema
+                v-if="content.schema && (isSchemaObject(content.schema) || isArraySchemaObject(content.schema))"
+                :schema="content.schema" />
             </div>
           </DetailsExpand>
         </template>
@@ -63,6 +65,7 @@
 
 <script setup lang="ts">
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import {isParameterType, isArraySchemaObject, isSchemaObject} from '@mptheme/client/utils/openApiGuards';
 import OpenApiSchema from './OpenApiSchema.vue';
 import OpenApiResponses from './OpenApiResponses.vue';
 import OpenApiRequestParam from './OpenApiRequestParam.vue';
@@ -74,10 +77,4 @@ defineProps<{
   title: string;
   path: OpenApiType.PathItemObject;
 }>();
-
-function isParameterType(
-  parameter: OpenApiType.ParameterObject | OpenApiType.ReferenceObject,
-): parameter is OpenApiType.ParameterObject {
-  return 'in' in parameter && 'schema' in parameter;
-}
 </script>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
index a0bf47c0..d7efaa44 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
@@ -65,6 +65,7 @@
 <script setup lang="ts">
 import {computed, type ComputedRef} from 'vue';
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import {isReponseObject} from '@mptheme/client/utils/openApiGuards';
 import OpenApiSchema from './OpenApiSchema.vue';
 import Http from './Http.vue';
 import DetailsExpand from './DetailsExpand.vue';
@@ -74,11 +75,6 @@ const props = defineProps<{
   responses: OpenApiType.ResponsesObject;
 }>();
 
-// Guard to check if the response is an OpenApiType.ResponseObject.
-const isReponseObject = (response: object): response is OpenApiType.ResponseObject => {
-  return typeof response === 'object';
-};
-
 // Adds a computed to get only the OpenApiType.ResponseObject types from the responses prop.
 const responseObjects: ComputedRef<Record<string, OpenApiType.ResponseObject>> = computed(() => {
   const objects: Record<string, OpenApiType.ResponseObject> = {};
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSchema.vue b/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
index 6f279b62..cd889ad6 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
@@ -131,6 +131,7 @@
 <script setup lang="ts">
 import {ref} from 'vue';
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import {isArraySchemaObject, isSchemaObject} from '@mptheme/client/utils/openApiGuards';
 import OpenApiSchemaInfo from './OpenApiSchemaInfo.vue';
 
 defineProps<{
@@ -141,16 +142,6 @@ defineProps<{
 
 const showNested = ref(false);
 
-// Guard to check if the schema is an OpenApiType.SchemaObject.
-const isSchemaObject = (schema: object): schema is OpenApiType.SchemaObject => {
-  return typeof schema === 'object';
-};
-
-// Guard to check if the schema is an OpenApiType.ArraySchemaObject.
-const isArraySchemaObject = (schema: object): schema is OpenApiType.ArraySchemaObject => {
-  return typeof schema === 'object' && 'items' in schema;
-};
-
 function anyPropertyHasNesting(properties: OpenApiType.SchemaObject['properties']) {
   return properties
     ? Object.keys(properties).some((key) => propertyHasNesting(key, Object.keys(properties[key])))
diff --git a/src/.vuepress/theme/client/utils/openApiGuards.ts b/src/.vuepress/theme/client/utils/openApiGuards.ts
new file mode 100644
index 00000000..16f0dd87
--- /dev/null
+++ b/src/.vuepress/theme/client/utils/openApiGuards.ts
@@ -0,0 +1,22 @@
+import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+
+export function isParameterType(
+  parameter: OpenApiType.ParameterObject | OpenApiType.ReferenceObject,
+): parameter is OpenApiType.ParameterObject {
+  return 'in' in parameter && 'schema' in parameter;
+}
+
+// Guard to check if the schema is an OpenApiType.SchemaObject.
+export const isSchemaObject = (schema: object): schema is OpenApiType.SchemaObject => {
+  return typeof schema === 'object';
+};
+
+// Guard to check if the schema is an OpenApiType.ArraySchemaObject.
+export const isArraySchemaObject = (schema: object): schema is OpenApiType.ArraySchemaObject => {
+  return typeof schema === 'object' && 'items' in schema;
+};
+
+// Guard to check if the response is an OpenApiType.ResponseObject.
+export const isReponseObject = (response: object): response is OpenApiType.ResponseObject => {
+  return typeof response === 'object';
+};

From eb5141a4734ee4d40c6a1c0d14e33046cc1d776b Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Wed, 10 Apr 2024 15:51:44 +0200
Subject: [PATCH 18/41] fix(open-api): fix tables not showing correctly in dark
 mode

INT-407
---
 .../theme/client/components/global/OpenApiSchema.vue          | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/.vuepress/theme/client/components/global/OpenApiSchema.vue b/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
index cd889ad6..91c81c5d 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
@@ -12,8 +12,8 @@
 
     <table
       v-if="isSchemaObject(schema) && schema.properties"
-      class="bg-gray-50 border-collapse border-spacing-0 table-auto">
-      <thead class="bg-gray-200">
+      class="border-collapse border-spacing-0 table-auto">
+      <thead class="bg-gray-200 dark:bg-opacity-10">
         <th>Name</th>
         <th v-if="anyPropertyHasNesting(schema.properties)">Content</th>
       </thead>

From b31b8fdb68438ef8efd2f49dea5697788a23df67 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Thu, 11 Apr 2024 13:48:12 +0200
Subject: [PATCH 19/41] feat(open-api): add a plugin to render openapi schema
 files as markdown pages

adds a plugin to render json openapi files from a directory into individual pages within vuepress, with each path within as a chapter

INT-407
---
 src/.vuepress/config.ts                       |   5 +
 src/.vuepress/plugins/openApi.ts              |  61 ++
 .../theme/client/components/global/index.ts   |  12 +
 .../theme/client/utils/openApiHelpers.ts      |  41 ++
 src/api-reference/9999.test.md                | 683 ------------------
 src/openapi/Petstore Expanded.json            | 242 +++++++
 src/openapi/callback-example.json             |  84 +++
 src/openapi/webhooks.json                     | 331 +++++++++
 8 files changed, 776 insertions(+), 683 deletions(-)
 create mode 100644 src/.vuepress/plugins/openApi.ts
 create mode 100644 src/.vuepress/theme/client/utils/openApiHelpers.ts
 delete mode 100644 src/api-reference/9999.test.md
 create mode 100644 src/openapi/Petstore Expanded.json
 create mode 100644 src/openapi/callback-example.json
 create mode 100644 src/openapi/webhooks.json

diff --git a/src/.vuepress/config.ts b/src/.vuepress/config.ts
index fcbac78e..fc01f307 100755
--- a/src/.vuepress/config.ts
+++ b/src/.vuepress/config.ts
@@ -6,6 +6,7 @@ import {viteConfig} from './viteConfig';
 import {myParcelTheme} from './theme';
 import {sitemapPlugin} from './plugins/sitemap';
 import {parseTranslationsPlugin} from './plugins/parseTranslations';
+import {openApiPlugin} from './plugins/openApi';
 import {googleTagManagerPlugin} from './plugins/gtm/node';
 import {DIR_CONFIG, DIR_VUEPRESS} from './dirs';
 import {head} from './config/head';
@@ -25,6 +26,10 @@ export default defineUserConfig({
   }),
 
   plugins: [
+    openApiPlugin({
+      specsDir: 'src/openapi',
+    }),
+
     parseTranslationsPlugin({
       defaultLocale: 'en-GB',
       configDir: path.resolve(DIR_CONFIG, 'navigation'),
diff --git a/src/.vuepress/plugins/openApi.ts b/src/.vuepress/plugins/openApi.ts
new file mode 100644
index 00000000..dbbbaa8d
--- /dev/null
+++ b/src/.vuepress/plugins/openApi.ts
@@ -0,0 +1,61 @@
+import fs from 'fs';
+import {createPage, type Plugin} from 'vuepress';
+import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import {resolveRefs} from '../theme/client/utils/openApiHelpers';
+
+interface OpenApiPluginConfig {
+  specsDir: string;
+}
+
+export const openApiPlugin = (config: OpenApiPluginConfig): Plugin => ({
+  name: '@myparcel/vuepress-openapi',
+  onInitialized(app) {
+    // Find all .json files in config.spesDir and create a page for each of them
+    fs.readdir(config.specsDir, (err, files) => {
+      files.forEach(async (file) => {
+        // If the file is a .json file, create a page for it
+        if (file.endsWith('.json')) {
+          // Read the file and parse it as JSON
+          const spec = JSON.parse(fs.readFileSync(`${config.specsDir}/${file}`).toString()) as OpenApiType.Document;
+          // Use the basename of the file as the slug
+          const slug = file.replace('.json', '');
+          // Now generate the page contents
+          app.pages.push(
+            await createPage(app, {
+              path: `/api-reference/${slug}`,
+              content: `\
+---
+title: ${spec.info.title}
+description: ${spec.info.description}
+---
+Version ${spec.info.version}
+
+${spec.info.description ?? ''}
+
+${renderChapters(spec)}
+          `,
+            }),
+          );
+        }
+      });
+    });
+  },
+});
+
+function renderChapters(document: OpenApiType.Document): string {
+  const resolvedDocument = resolveRefs(document);
+
+  let chapters = '';
+
+  if (resolvedDocument.paths) {
+    for (const [path, pathObj] of Object.entries(resolvedDocument.paths)) {
+      chapters += `
+## ${path}
+\n
+<OpenApiPath :path='${JSON.stringify(pathObj)}' title='${path}' />
+    `;
+    }
+  }
+
+  return chapters;
+}
diff --git a/src/.vuepress/theme/client/components/global/index.ts b/src/.vuepress/theme/client/components/global/index.ts
index 96cf0ace..910e65d5 100644
--- a/src/.vuepress/theme/client/components/global/index.ts
+++ b/src/.vuepress/theme/client/components/global/index.ts
@@ -64,3 +64,15 @@ export {default as Stack} from './Stack.vue';
 export {default as TeamMember} from './TeamMember.vue';
 
 export {default as OpenApi} from './OpenApi.vue';
+
+export {default as OpenApiExample} from './OpenApiExample.vue';
+
+export {default as OpenApiPath} from './OpenApiPath.vue';
+
+export {default as OpenApiRequestParam} from './OpenApiRequestParam.vue';
+
+export {default as OpenApiResponses} from './OpenApiResponses.vue';
+
+export {default as OpenApiSchema} from './OpenApiSchema.vue';
+
+export {default as OpenApiSchemaInfo} from './OpenApiSchemaInfo.vue';
diff --git a/src/.vuepress/theme/client/utils/openApiHelpers.ts b/src/.vuepress/theme/client/utils/openApiHelpers.ts
new file mode 100644
index 00000000..7b564b79
--- /dev/null
+++ b/src/.vuepress/theme/client/utils/openApiHelpers.ts
@@ -0,0 +1,41 @@
+import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import {get} from 'lodash-es';
+
+type RecursiveType = {
+  [key: string]: unknown | RecursiveType | RecursiveType[];
+};
+
+/**
+ * Resolves all $ref keys in the document with their corresponding values
+ */
+export function resolveRefs(document: OpenApiType.Document): OpenApiType.Document {
+  const resolvedDocument = {...document};
+
+  function resolveRefsRecursive(obj: RecursiveType) {
+    if (Array.isArray(obj)) {
+      for (const item of obj) {
+        resolveRefsRecursive(item);
+      }
+    } else if (typeof obj === 'object') {
+      for (const key in obj) {
+        if (key === '$ref') {
+          const lookup = obj[key] as string;
+          // Lookup is a string that defines the path to the referenced object like '#/components/schemas/Example'
+          const path = lookup.split('/').slice(1);
+          // Find the referenced object in the document using lodash's get function
+          const referencedObject = get(resolvedDocument, path);
+          // Remove the $ref: '...' key from the object and replace it with the referenced object itself
+          obj = Object.assign(obj, referencedObject);
+        } else if (typeof obj[key] === 'object' || Array.isArray(obj[key])) {
+          const guarded = obj[key] as RecursiveType;
+          // If the value is an object or an array, recursively call this function
+          resolveRefsRecursive(guarded);
+        }
+      }
+    }
+  }
+
+  resolveRefsRecursive(resolvedDocument);
+
+  return resolvedDocument;
+}
diff --git a/src/api-reference/9999.test.md b/src/api-reference/9999.test.md
deleted file mode 100644
index 5f538979..00000000
--- a/src/api-reference/9999.test.md
+++ /dev/null
@@ -1,683 +0,0 @@
----
-title: 9999. Test
----
-
-<OpenApi :document="{
-  openapi: '3.1.0',
-  info: {
-    title: 'MyParcel Core-API',
-    contact: {
-      name: 'IT Support',
-      url: ':support@myparcel.nl'
-    },
-    version: '4.0.0'
-  },
-  servers: [
-    {
-      url: 'https://api.myparcel.nl',
-      description: 'MyParcel Production Server'
-    }
-  ],
-  paths: {
-    '/webhook_subscriptions': {
-      get: {
-        tags: ['Webhook Subscriptions'],
-        description: 'Show list of webhook subscriptions',
-        operationId: 'getSubscriptions',
-        parameters: [
-          { $ref: '#/components/parameters/user_agent_header' },
-          { $ref: '#/components/parameters/account_id' },
-          { $ref: '#/components/parameters/shop_id' },
-          {
-            name: 'hook',
-            in: 'query',
-            description: 'The event from which you want to receive notifications',
-            required: false,
-            schema: {
-              description: 'The event from which you want to receive notifications',
-              type: 'string',
-              example: 'shipment_status_change'
-            }
-          }
-        ],
-        responses: {
-          '200': {
-            description: 'OK',
-            content: {
-              'application/json; charset: utf-8': {
-                schema: {
-                  $ref: '#/components/schemas/webhook_subscriptions_response'
-                }
-              }
-            }
-          },
-          '400': { description: 'Validation error' },
-          '401': { description: 'Unauthorized' },
-          '403': { description: 'Forbidden' },
-          '500': { description: 'Internal Server Error' }
-        },
-        security: []
-      },
-      post: {
-        tags: ['Webhook Subscriptions'],
-        description: 'Add new webhook subscription.',
-        operationId: 'postSubscriptions',
-        parameters: [{ $ref: '#/components/parameters/user_agent_header' }],
-        requestBody: {
-          description: `| **Hook** | **Description** |
-|---- |------------|
-| \`shipment_status_change\` | Whenever the shipment_status of a shipment changes, this webhook will send you an update with the new value. We will not send an update with a status.|
-| \`shipment_label_created\` | When a label is created asynchronously (for example when creating shipments using accept header \`application/vnd.shipment_label+json;charset=utf-8\`), this webhook will send you a message with the URL of the label. |
-| \`order_status_change\` | Whenever the order_status of an order changes, this webhook will send you an update with the new value. |`,
-          required: true,
-          content: {
-            'application/json; charset: utf-8': {
-              schema: {
-                $ref: '#/components/schemas/webhook_subscription_request'
-              }
-            }
-          }
-        },
-        responses: {
-          '201': {
-            description: 'Response with array of webhook ids',
-            content: {
-              'application/json; charset: utf-8': {
-                example: {
-                  data: {
-                    webhook_subscriptions: [{ id: 1 }]
-                  }
-                }
-              }
-            }
-          },
-          '400': { description: 'Validation error' },
-          '401': { description: 'Unauthorized' },
-          '403': { description: 'Forbidden' },
-          '500': { description: 'Internal Server Error' }
-        },
-        security: []
-      }
-    },
-    '/webhook_subscriptions/{webhook_subscriptions_id}': {
-      delete: {
-        tags: ['Webhook Subscriptions'],
-        summary: 'Delete webhook subscriptions.',
-        description: 'Delete a webhook subscription',
-        operationId: 'deleteSubscriptions',
-        parameters: [
-          { $ref: '#/components/parameters/user_agent_header' },
-          { $ref: '#/components/parameters/webhook_subscriptions_id_in_path' }
-        ],
-        responses: {
-          '204': { description: 'No content' },
-          '401': { description: 'Unauthorized' },
-          '403': { description: 'Forbidden' },
-          '500': { description: 'Internal Server Error' }
-        },
-        security: []
-      }
-    }
-  },
-  components: {
-    schemas: {
-      webhook_subscriptions_response: {
-        required: ['data'],
-        properties: {
-          data: {
-            required: ['webhook_subscriptions'],
-            properties: {
-              webhook_subscriptions: {
-                type: 'array',
-                items: { $ref: '#/components/schemas/webhook_subscription' }
-              }
-            },
-            type: 'object'
-          }
-        },
-        type: 'object'
-      },
-      webhook_subscription: {
-        description: 'Webhook subscription',
-        required: ['id', 'account_id', 'shop_id', 'hook', 'url'],
-        properties: {
-          id: {
-            description: 'ID of webhook subscriptions',
-            type: 'integer',
-            format: 'int32',
-            example: 56123456
-          },
-          account_id: {
-            description: 'Account ID',
-            type: 'integer',
-            format: 'int32',
-            example: 125678
-          },
-          shop_id: {
-            description: 'Shop ID',
-            type: 'integer',
-            format: 'int32',
-            example: 1234
-          },
-          hook: {
-            description: 'The event from which you want to receive notifications',
-            type: 'string',
-            example: 'shipment_status_changed'
-          },
-          url: {
-            description: 'The callback URL on which to receive notifications',
-            type: 'string',
-            format: 'uri',
-            example: 'https://example.com/webhook'
-          }
-        },
-        type: 'object'
-      },
-      webhook_subscription_request: {
-        description: 'Webhook subscription request',
-        required: ['data'],
-        properties: {
-          data: {
-            required: ['webhook_subscription'],
-            properties: {
-              webhook_subscription: {
-                required: ['hook', 'url'],
-                properties: {
-                  hook: {
-                    description: 'The event from which you want to receive notifications',
-                    type: 'string',
-                    example: 'shipment_status_changed'
-                  },
-                  url: {
-                    description: 'The callback URL on which to receive notifications',
-                    type: 'string',
-                    format: 'uri',
-                    example: 'https://example.com/webhook'
-                  }
-                },
-                type: 'object'
-              }
-            },
-            type: 'object'
-          }
-        },
-        type: 'object'
-      }
-    },
-    parameters: {
-      account_id: {
-        name: 'account_id',
-        in: 'query',
-        description: 'The ID of the account.',
-        required: false,
-        schema: {
-          type: 'integer',
-          format: 'int32'
-        },
-        example: '123456'
-      },
-      shop_id: {
-        name: 'shop_id',
-        in: 'query',
-        description: 'The ID of the shop.',
-        required: false,
-        schema: {
-          type: 'integer',
-          format: 'int32'
-        },
-        example: '5678'
-      },
-      user_agent_header: {
-        name: 'User-Agent',
-        in: 'header',
-        description: 'The User-Agent header',
-        required: true,
-        schema: {
-          type: 'string'
-        },
-        example: 'NameOfMyApp/1.0.0 PHP/8.1.0'
-      },
-      webhook_subscriptions_id_in_path: {
-        name: 'webhook_subscriptions_id',
-        in: 'path',
-        description: 'The ID of the webhook subscription',
-        required: true,
-        schema: {
-          type: 'integer',
-          format: 'int32'
-        },
-        example: '123456789'
-      }
-    },
-    securitySchemes: {
-      bearerAuth: {
-        type: 'http',
-        description: 'BASE64 encoded ',
-        name: 'Authorization',
-        in: 'header',
-        scheme: 'bearer'
-      }
-    }
-  },
-  tags: [
-    {
-      name: 'Pickup Locations',
-      description: 'All about Pickup Locations'
-    },
-    {
-      name: 'Webhook Subscriptions',
-      description: 'All about Webhooks'
-    }
-  ]
-}" />
-
-<OpenApi :document="{
-  'openapi': '3.0.0',
-  'info': {
-    'version': '1.0.0',
-    'title': 'Swagger Petstore',
-    'description': 'A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification',
-    'termsOfService': 'http://swagger.io/terms/',
-    'contact': {
-      'name': 'Swagger API Team',
-      'email': 'apiteam@swagger.io',
-      'url': 'http://swagger.io'
-    },
-    'license': {
-      'name': 'Apache 2.0',
-      'url': 'https://www.apache.org/licenses/LICENSE-2.0.html'
-    }
-  },
-  'servers': [
-    {
-      'url': 'https://petstore.swagger.io/v2'
-    }
-  ],
-  'paths': {
-    '/pets': {
-      'get': {
-        'description': 'Returns all pets from the system that the user has access to\nNam sed condimentum est. Maecenas tempor sagittis sapien, nec rhoncus sem sagittis sit amet. Aenean at gravida augue, ac iaculis sem. Curabitur odio lorem, ornare eget elementum nec, cursus id lectus. Duis mi turpis, pulvinar ac eros ac, tincidunt varius justo. In hac habitasse platea dictumst. Integer at adipiscing ante, a sagittis ligula. Aenean pharetra tempor ante molestie imperdiet. Vivamus id aliquam diam. Cras quis velit non tortor eleifend sagittis. Praesent at enim pharetra urna volutpat venenatis eget eget mauris. In eleifend fermentum facilisis. Praesent enim enim, gravida ac sodales sed, placerat id erat. Suspendisse lacus dolor, consectetur non augue vel, vehicula interdum libero. Morbi euismod sagittis libero sed lacinia.\n\nSed tempus felis lobortis leo pulvinar rutrum. Nam mattis velit nisl, eu condimentum ligula luctus nec. Phasellus semper velit eget aliquet faucibus. In a mattis elit. Phasellus vel urna viverra, condimentum lorem id, rhoncus nibh. Ut pellentesque posuere elementum. Sed a varius odio. Morbi rhoncus ligula libero, vel eleifend nunc tristique vitae. Fusce et sem dui. Aenean nec scelerisque tortor. Fusce malesuada accumsan magna vel tempus. Quisque mollis felis eu dolor tristique, sit amet auctor felis gravida. Sed libero lorem, molestie sed nisl in, accumsan tempor nisi. Fusce sollicitudin massa ut lacinia mattis. Sed vel eleifend lorem. Pellentesque vitae felis pretium, pulvinar elit eu, euismod sapien.\n',
-        'operationId': 'findPets',
-        'parameters': [
-          {
-            'name': 'tags',
-            'in': 'query',
-            'description': 'tags to filter by',
-            'required': false,
-            'style': 'form',
-            'schema': {
-              'type': 'array',
-              'items': {
-                'type': 'string'
-              }
-            }
-          },
-          {
-            'name': 'limit',
-            'in': 'query',
-            'description': 'maximum number of results to return',
-            'required': false,
-            'schema': {
-              'type': 'integer',
-              'format': 'int32'
-            }
-          }
-        ],
-        'responses': {
-          '200': {
-            'description': 'pet response',
-            'content': {
-              'application/json': {
-                'schema': {
-                  'type': 'array',
-                  'items': {
-                    '$ref': '#/components/schemas/Pet'
-                  }
-                }
-              }
-            }
-          },
-          'default': {
-            'description': 'unexpected error',
-            'content': {
-              'application/json': {
-                'schema': {
-                  '$ref': '#/components/schemas/Error'
-                }
-              }
-            }
-          }
-        }
-      },
-      'post': {
-        'description': 'Creates a new pet in the store. Duplicates are allowed',
-        'operationId': 'addPet',
-        'requestBody': {
-          'description': 'Pet to add to the store',
-          'required': true,
-          'content': {
-            'application/json': {
-              'schema': {
-                '$ref': '#/components/schemas/NewPet'
-              }
-            }
-          }
-        },
-        'responses': {
-          '200': {
-            'description': 'pet response',
-            'content': {
-              'application/json': {
-                'schema': {
-                  '$ref': '#/components/schemas/Pet'
-                }
-              }
-            }
-          },
-          'default': {
-            'description': 'unexpected error',
-            'content': {
-              'application/json': {
-                'schema': {
-                  '$ref': '#/components/schemas/Error'
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    '/pets/{id}': {
-      'get': {
-        'description': 'Returns a user based on a single ID, if the user does not have access to the pet',
-        'operationId': 'find pet by id',
-        'parameters': [
-          {
-            'name': 'id',
-            'in': 'path',
-            'description': 'ID of pet to fetch',
-            'required': true,
-            'schema': {
-              'type': 'integer',
-              'format': 'int64'
-            }
-          }
-        ],
-        'responses': {
-          '200': {
-            'description': 'pet response',
-            'content': {
-              'application/json': {
-                'schema': {
-                  '$ref': '#/components/schemas/Pet'
-                }
-              }
-            }
-          },
-          'default': {
-            'description': 'unexpected error',
-            'content': {
-              'application/json': {
-                'schema': {
-                  '$ref': '#/components/schemas/Error'
-                }
-              }
-            }
-          }
-        }
-      },
-      'delete': {
-        'description': 'deletes a single pet based on the ID supplied',
-        'operationId': 'deletePet',
-        'parameters': [
-          {
-            'name': 'id',
-            'in': 'path',
-            'description': 'ID of pet to delete',
-            'required': true,
-            'schema': {
-              'type': 'integer',
-              'format': 'int64'
-            }
-          }
-        ],
-        'responses': {
-          '204': {
-            'description': 'pet deleted'
-          },
-          'default': {
-            'description': 'unexpected error',
-            'content': {
-              'application/json': {
-                'schema': {
-                  '$ref': '#/components/schemas/Error'
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-  },
-  'components': {
-    'schemas': {
-      'Pet': {
-        'allOf': [
-          {
-            '$ref': '#/components/schemas/NewPet'
-          },
-          {
-            'type': 'object',
-            'required': [
-              'id'
-            ],
-            'properties': {
-              'id': {
-                'type': 'integer',
-                'format': 'int64'
-              }
-            }
-          }
-        ]
-      },
-      'NewPet': {
-        'type': 'object',
-        'required': [
-          'name'
-        ],
-        'properties': {
-          'name': {
-            'type': 'string'
-          },
-          'tag': {
-            'type': 'string'
-          }
-        }
-      },
-      'Error': {
-        'type': 'object',
-        'required': [
-          'code',
-          'message'
-        ],
-        'properties': {
-          'code': {
-            'type': 'integer',
-            'format': 'int32'
-          },
-          'message': {
-            'type': 'string'
-          }
-        }
-      }
-    }
-  }
-}" />
-
-<OpenApi :document="{
-  'openapi': '3.0.0',
-  'info': {
-    'title': 'Simple API overview',
-    'version': '2.0.0'
-  },
-  'paths': {
-    '/': {
-      'get': {
-        'operationId': 'listVersionsv2',
-        'summary': 'List API versions',
-        'responses': {
-          '200': {
-            'description': '200 response',
-            'content': {
-              'application/json': {
-                'examples': {
-                  'foo': {
-                    'value': {
-                      'versions': [
-                        {
-                          'status': 'CURRENT',
-                          'updated': '2011-01-21T11:33:21Z',
-                          'id': 'v2.0',
-                          'links': [
-                            {
-                              'href': 'http://127.0.0.1:8774/v2/',
-                              'rel': 'self'
-                            }
-                          ]
-                        },
-                        {
-                          'status': 'EXPERIMENTAL',
-                          'updated': '2013-07-23T11:33:21Z',
-                          'id': 'v3.0',
-                          'links': [
-                            {
-                              'href': 'http://127.0.0.1:8774/v3/',
-                              'rel': 'self'
-                            }
-                          ]
-                        }
-                      ]
-                    }
-                  }
-                }
-              }
-            }
-          },
-          '300': {
-            'description': '300 response',
-            'content': {
-              'application/json': {
-                'examples': {
-                  'foo': {
-                    'value': '{\n \'versions\': [\n       {\n         \'status\': \'CURRENT\',\n         \'updated\': \'2011-01-21T11:33:21Z\',\n         \'id\': \'v2.0\',\n         \'links\': [\n             {\n                 \'href\': \'http://127.0.0.1:8774/v2/\',\n                 \'rel\': \'self\'\n             }\n         ]\n     },\n     {\n         \'status\': \'EXPERIMENTAL\',\n         \'updated\': \'2013-07-23T11:33:21Z\',\n         \'id\': \'v3.0\',\n         \'links\': [\n             {\n                 \'href\': \'http://127.0.0.1:8774/v3/\',\n                 \'rel\': \'self\'\n             }\n         ]\n     }\n ]\n}\n'
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    '/v2': {
-      'get': {
-        'operationId': 'getVersionDetailsv2',
-        'summary': 'Show API version details',
-        'responses': {
-          '200': {
-            'description': '200 response',
-            'content': {
-              'application/json': {
-                'examples': {
-                  'foo': {
-                    'value': {
-                      'version': {
-                        'status': 'CURRENT',
-                        'updated': '2011-01-21T11:33:21Z',
-                        'media-types': [
-                          {
-                            'base': 'application/xml',
-                            'type': 'application/vnd.openstack.compute+xml;version=2'
-                          },
-                          {
-                            'base': 'application/json',
-                            'type': 'application/vnd.openstack.compute+json;version=2'
-                          }
-                        ],
-                        'id': 'v2.0',
-                        'links': [
-                          {
-                            'href': 'http://127.0.0.1:8774/v2/',
-                            'rel': 'self'
-                          },
-                          {
-                            'href': 'http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf',
-                            'type': 'application/pdf',
-                            'rel': 'describedby'
-                          },
-                          {
-                            'href': 'http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl',
-                            'type': 'application/vnd.sun.wadl+xml',
-                            'rel': 'describedby'
-                          },
-                          {
-                            'href': 'http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl',
-                            'type': 'application/vnd.sun.wadl+xml',
-                            'rel': 'describedby'
-                          }
-                        ]
-                      }
-                    }
-                  }
-                }
-              }
-            }
-          },
-          '203': {
-            'description': '203 response',
-            'content': {
-              'application/json': {
-                'examples': {
-                  'foo': {
-                    'value': {
-                      'version': {
-                        'status': 'CURRENT',
-                        'updated': '2011-01-21T11:33:21Z',
-                        'media-types': [
-                          {
-                            'base': 'application/xml',
-                            'type': 'application/vnd.openstack.compute+xml;version=2'
-                          },
-                          {
-                            'base': 'application/json',
-                            'type': 'application/vnd.openstack.compute+json;version=2'
-                          }
-                        ],
-                        'id': 'v2.0',
-                        'links': [
-                          {
-                            'href': 'http://23.253.228.211:8774/v2/',
-                            'rel': 'self'
-                          },
-                          {
-                            'href': 'http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf',
-                            'type': 'application/pdf',
-                            'rel': 'describedby'
-                          },
-                          {
-                            'href': 'http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl',
-                            'type': 'application/vnd.sun.wadl+xml',
-                            'rel': 'describedby'
-                          }
-                        ]
-                      }
-                    }
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}" />
diff --git a/src/openapi/Petstore Expanded.json b/src/openapi/Petstore Expanded.json
new file mode 100644
index 00000000..420eede6
--- /dev/null
+++ b/src/openapi/Petstore Expanded.json	
@@ -0,0 +1,242 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "version": "1.0.0",
+    "title": "Swagger Petstore",
+    "description": "A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification",
+    "termsOfService": "http://swagger.io/terms/",
+    "contact": {
+      "name": "Swagger API Team",
+      "email": "apiteam@swagger.io",
+      "url": "http://swagger.io"
+    },
+    "license": {
+      "name": "Apache 2.0",
+      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://petstore.swagger.io/v2"
+    }
+  ],
+  "paths": {
+    "/pets": {
+      "get": {
+        "description": "Returns all pets from the system that the user has access to\nNam sed condimentum est. Maecenas tempor sagittis sapien, nec rhoncus sem sagittis sit amet. Aenean at gravida augue, ac iaculis sem. Curabitur odio lorem, ornare eget elementum nec, cursus id lectus. Duis mi turpis, pulvinar ac eros ac, tincidunt varius justo. In hac habitasse platea dictumst. Integer at adipiscing ante, a sagittis ligula. Aenean pharetra tempor ante molestie imperdiet. Vivamus id aliquam diam. Cras quis velit non tortor eleifend sagittis. Praesent at enim pharetra urna volutpat venenatis eget eget mauris. In eleifend fermentum facilisis. Praesent enim enim, gravida ac sodales sed, placerat id erat. Suspendisse lacus dolor, consectetur non augue vel, vehicula interdum libero. Morbi euismod sagittis libero sed lacinia.\n\nSed tempus felis lobortis leo pulvinar rutrum. Nam mattis velit nisl, eu condimentum ligula luctus nec. Phasellus semper velit eget aliquet faucibus. In a mattis elit. Phasellus vel urna viverra, condimentum lorem id, rhoncus nibh. Ut pellentesque posuere elementum. Sed a varius odio. Morbi rhoncus ligula libero, vel eleifend nunc tristique vitae. Fusce et sem dui. Aenean nec scelerisque tortor. Fusce malesuada accumsan magna vel tempus. Quisque mollis felis eu dolor tristique, sit amet auctor felis gravida. Sed libero lorem, molestie sed nisl in, accumsan tempor nisi. Fusce sollicitudin massa ut lacinia mattis. Sed vel eleifend lorem. Pellentesque vitae felis pretium, pulvinar elit eu, euismod sapien.\n",
+        "operationId": "findPets",
+        "parameters": [
+          {
+            "name": "tags",
+            "in": "query",
+            "description": "tags to filter by",
+            "required": false,
+            "style": "form",
+            "schema": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "description": "maximum number of results to return",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "format": "int32"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "pet response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/Pet"
+                  }
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "unexpected error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "description": "Creates a new pet in the store. Duplicates are allowed",
+        "operationId": "addPet",
+        "requestBody": {
+          "description": "Pet to add to the store",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/NewPet"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "pet response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Pet"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "unexpected error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/pets/{id}": {
+      "get": {
+        "description": "Returns a user based on a single ID, if the user does not have access to the pet",
+        "operationId": "find pet by id",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "ID of pet to fetch",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "pet response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Pet"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "unexpected error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "description": "deletes a single pet based on the ID supplied",
+        "operationId": "deletePet",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "ID of pet to delete",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "format": "int64"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "pet deleted"
+          },
+          "default": {
+            "description": "unexpected error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Pet": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/NewPet"
+          },
+          {
+            "type": "object",
+            "required": [
+              "id"
+            ],
+            "properties": {
+              "id": {
+                "type": "integer",
+                "format": "int64"
+              }
+            }
+          }
+        ]
+      },
+      "NewPet": {
+        "type": "object",
+        "required": [
+          "name"
+        ],
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "tag": {
+            "type": "string"
+          }
+        }
+      },
+      "Error": {
+        "type": "object",
+        "required": [
+          "code",
+          "message"
+        ],
+        "properties": {
+          "code": {
+            "type": "integer",
+            "format": "int32"
+          },
+          "message": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}
\ No newline at end of file
diff --git a/src/openapi/callback-example.json b/src/openapi/callback-example.json
new file mode 100644
index 00000000..9a4df39b
--- /dev/null
+++ b/src/openapi/callback-example.json
@@ -0,0 +1,84 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Callback Example",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/streams": {
+      "post": {
+        "description": "subscribes a client to receive out-of-band data",
+        "parameters": [
+          {
+            "name": "callbackUrl",
+            "in": "query",
+            "required": true,
+            "description": "the location where data will be sent.  Must be network accessible\nby the source server\n",
+            "schema": {
+              "type": "string",
+              "format": "uri",
+              "example": "https://tonys-server.com"
+            }
+          }
+        ],
+        "responses": {
+          "201": {
+            "description": "subscription successfully created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "description": "subscription information",
+                  "required": [
+                    "subscriptionId"
+                  ],
+                  "properties": {
+                    "subscriptionId": {
+                      "description": "this unique identifier allows management of the subscription",
+                      "type": "string",
+                      "example": "2531329f-fb09-4ef7-887e-84e648214436"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "callbacks": {
+          "onData": {
+            "{$request.query.callbackUrl}/data": {
+              "post": {
+                "requestBody": {
+                  "description": "subscription payload",
+                  "content": {
+                    "application/json": {
+                      "schema": {
+                        "type": "object",
+                        "properties": {
+                          "timestamp": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "userData": {
+                            "type": "string"
+                          }
+                        }
+                      }
+                    }
+                  }
+                },
+                "responses": {
+                  "202": {
+                    "description": "Your server implementation should return this HTTP status code\nif the data was received successfully\n"
+                  },
+                  "204": {
+                    "description": "Your server should return this HTTP status code if no longer interested\nin further updates\n"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
\ No newline at end of file
diff --git a/src/openapi/webhooks.json b/src/openapi/webhooks.json
new file mode 100644
index 00000000..a7427522
--- /dev/null
+++ b/src/openapi/webhooks.json
@@ -0,0 +1,331 @@
+{
+    "openapi": "3.1.0",
+    "info": {
+        "title": "MyParcel Core-API",
+        "contact": {
+            "name": "IT Support",
+            "url": "support@myparcel.nl"
+        },
+        "version": "4.0.0"
+    },
+    "servers": [
+        {
+            "url": "https://api.myparcel.nl",
+            "description": "MyParcel Production Server"
+        }
+    ],
+    "paths": {
+        "/webhook_subscriptions": {
+            "get": {
+                "tags": [
+                    "Webhook Subscriptions"
+                ],
+                "description": "Show list of webhook subscriptions",
+                "operationId": "getSubscriptions",
+                "parameters": [
+                    {
+                        "$ref": "#/components/parameters/user_agent_header"
+                    },
+                    {
+                        "$ref": "#/components/parameters/account_id"
+                    },
+                    {
+                        "$ref": "#/components/parameters/shop_id"
+                    },
+                    {
+                        "name": "hook",
+                        "in": "query",
+                        "description": "The event from which you want to receive notifications",
+                        "required": false,
+                        "schema": {
+                            "description": "The event from which you want to receive notifications",
+                            "type": "string",
+                            "example": "shipment_status_change"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "content": {
+                            "application/json; charset=utf-8": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/webhook_subscriptions_response"
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "Validation error"
+                    },
+                    "401": {
+                        "description": "Unauthorized"
+                    },
+                    "403": {
+                        "description": "Forbidden"
+                    },
+                    "500": {
+                        "description": "Internal Server Error"
+                    }
+                },
+                "security": []
+            },
+            "post": {
+                "tags": [
+                    "Webhook Subscriptions"
+                ],
+                "description": "Add new webhook subscription.",
+                "operationId": "postSubscriptions",
+                "parameters": [
+                    {
+                        "$ref": "#/components/parameters/user_agent_header"
+                    }
+                ],
+                "requestBody": {
+                    "description": "| **Hook** | **Description** |\n|---- |------------|\n| `shipment_status_change` | Whenever the shipment_status of a shipment changes, this webhook will send you an update with the new value. We will not send an update with a status.|\n| `shipment_label_created` | When a label is created asynchronously (for example when creating shipments using accept header `application/vnd.shipment_label+json;charset=utf-8`), this webhook will send you a message with the URL of the label. |\n| `order_status_change` | Whenever the order_status of an order changes, this webhook will send you an update with the new value. |",
+                    "required": true,
+                    "content": {
+                        "application/json; charset=utf-8": {
+                            "schema": {
+                                "$ref": "#/components/schemas/webhook_subscription_request"
+                            }
+                        }
+                    }
+                },
+                "responses": {
+                    "201": {
+                        "description": "Response with array of webhook ids",
+                        "content": {
+                            "application/json; charset=utf-8": {
+                                "example": {
+                                    "data": {
+                                        "webhook_subscriptions": [
+                                            {
+                                                "id": 1
+                                            }
+                                        ]
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "Validation error"
+                    },
+                    "401": {
+                        "description": "Unauthorized"
+                    },
+                    "403": {
+                        "description": "Forbidden"
+                    },
+                    "500": {
+                        "description": "Internal Server Error"
+                    }
+                },
+                "security": []
+            }
+        },
+        "/webhook_subscriptions/{webhook_subscriptions_id}": {
+            "delete": {
+                "tags": [
+                    "Webhook Subscriptions"
+                ],
+                "summary": "Delete webhook subscriptions.",
+                "description": "Delete a webhook subscription",
+                "operationId": "deleteSubscriptions",
+                "parameters": [
+                    {
+                        "$ref": "#/components/parameters/user_agent_header"
+                    },
+                    {
+                        "$ref": "#/components/parameters/webhook_subscriptions_id_in_path"
+                    }
+                ],
+                "responses": {
+                    "204": {
+                        "description": "No content"
+                    },
+                    "401": {
+                        "description": "Unauthorized"
+                    },
+                    "403": {
+                        "description": "Forbidden"
+                    },
+                    "500": {
+                        "description": "Internal Server Error"
+                    }
+                },
+                "security": []
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "webhook_subscriptions_response": {
+                "required": [
+                    "data"
+                ],
+                "properties": {
+                    "data": {
+                        "required": [
+                            "webhook_subscriptions"
+                        ],
+                        "properties": {
+                            "webhook_subscriptions": {
+                                "type": "array",
+                                "items": {
+                                    "$ref": "#/components/schemas/webhook_subscription"
+                                }
+                            }
+                        },
+                        "type": "object"
+                    }
+                },
+                "type": "object"
+            },
+            "webhook_subscription": {
+                "description": "Webhook subscription",
+                "required": [
+                    "id",
+                    "account_id",
+                    "shop_id",
+                    "hook",
+                    "url"
+                ],
+                "properties": {
+                    "id": {
+                        "description": "ID of webhook subscriptions",
+                        "type": "integer",
+                        "format": "int32",
+                        "example": 56123456
+                    },
+                    "account_id": {
+                        "description": "Account ID",
+                        "type": "integer",
+                        "format": "int32",
+                        "example": 125678
+                    },
+                    "shop_id": {
+                        "description": "Shop ID",
+                        "type": "integer",
+                        "format": "int32",
+                        "example": 1234
+                    },
+                    "hook": {
+                        "description": "The event from which you want to receive notifications",
+                        "type": "string",
+                        "example": "shipment_status_changed"
+                    },
+                    "url": {
+                        "description": "The callback URL on which to receive notifications",
+                        "type": "string",
+                        "format": "uri",
+                        "example": "https://example.com/webhook"
+                    }
+                },
+                "type": "object"
+            },
+            "webhook_subscription_request": {
+                "description": "Webhook subscription request",
+                "required": [
+                    "data"
+                ],
+                "properties": {
+                    "data": {
+                        "required": [
+                            "webhook_subscription"
+                        ],
+                        "properties": {
+                            "webhook_subscription": {
+                                "required": [
+                                    "hook",
+                                    "url"
+                                ],
+                                "properties": {
+                                    "hook": {
+                                        "description": "The event from which you want to receive notifications",
+                                        "type": "string",
+                                        "example": "shipment_status_changed"
+                                    },
+                                    "url": {
+                                        "description": "The callback URL on which to receive notifications",
+                                        "type": "string",
+                                        "format": "uri",
+                                        "example": "https://example.com/webhook"
+                                    }
+                                },
+                                "type": "object"
+                            }
+                        },
+                        "type": "object"
+                    }
+                },
+                "type": "object"
+            }
+        },
+        "parameters": {
+            "account_id": {
+                "name": "account_id",
+                "in": "query",
+                "description": "The ID of the account.",
+                "required": false,
+                "schema": {
+                    "type": "integer",
+                    "format": "int32"
+                },
+                "example": "123456"
+            },
+            "shop_id": {
+                "name": "shop_id",
+                "in": "query",
+                "description": "The ID of the shop.",
+                "required": false,
+                "schema": {
+                    "type": "integer",
+                    "format": "int32"
+                },
+                "example": "5678"
+            },
+            "user_agent_header": {
+                "name": "User-Agent",
+                "in": "header",
+                "description": "The User-Agent header",
+                "required": true,
+                "schema": {
+                    "type": "string"
+                },
+                "example": "NameOfMyApp/1.0.0 PHP/8.1.0"
+            },
+            "webhook_subscriptions_id_in_path": {
+                "name": "webhook_subscriptions_id",
+                "in": "path",
+                "description": "The ID of the webhook subscription",
+                "required": true,
+                "schema": {
+                    "type": "integer",
+                    "format": "int32"
+                },
+                "example": "123456789"
+            }
+        },
+        "securitySchemes": {
+            "bearerAuth": {
+                "type": "http",
+                "description": "BASE64 encoded ",
+                "name": "Authorization",
+                "in": "header",
+                "scheme": "bearer"
+            }
+        }
+    },
+    "tags": [
+        {
+            "name": "Pickup Locations",
+            "description": "All about Pickup Locations"
+        },
+        {
+            "name": "Webhook Subscriptions",
+            "description": "All about Webhooks"
+        }
+    ]
+}

From bf7ea0b5a188d617ac8aca4301e0d7a6ec41c465 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Fri, 12 Apr 2024 10:08:38 +0200
Subject: [PATCH 20/41] refactor(open-api): load yaml files from (remote) url
 rather than json files from a local directory

INT-407
---
 package.json                       |   3 +-
 src/.vuepress/config.ts            |   2 +-
 src/.vuepress/plugins/openApi.ts   |  44 ++--
 src/openapi/Petstore Expanded.json | 242 ---------------------
 src/openapi/callback-example.json  |  84 --------
 src/openapi/webhooks.json          | 331 -----------------------------
 yarn.lock                          |  10 +
 7 files changed, 34 insertions(+), 682 deletions(-)
 delete mode 100644 src/openapi/Petstore Expanded.json
 delete mode 100644 src/openapi/callback-example.json
 delete mode 100644 src/openapi/webhooks.json

diff --git a/package.json b/package.json
index c0923698..4f3fbd6c 100755
--- a/package.json
+++ b/package.json
@@ -91,7 +91,8 @@
     "ts-node": "^10.9.1",
     "typescript": "^5.2.2",
     "vite-svg-loader": "^4.0.0",
-    "vitest": "^0.34.6"
+    "vitest": "^0.34.6",
+    "yaml": "^2.4.1"
   },
   "packageManager": "yarn@3.2.2",
   "volta": {
diff --git a/src/.vuepress/config.ts b/src/.vuepress/config.ts
index fc01f307..3e14f36b 100755
--- a/src/.vuepress/config.ts
+++ b/src/.vuepress/config.ts
@@ -27,7 +27,7 @@ export default defineUserConfig({
 
   plugins: [
     openApiPlugin({
-      specsDir: 'src/openapi',
+      yamlUrls: ['https://address.api.myparcel.nl/openapi.yaml'],
     }),
 
     parseTranslationsPlugin({
diff --git a/src/.vuepress/plugins/openApi.ts b/src/.vuepress/plugins/openApi.ts
index dbbbaa8d..eb0b73c7 100644
--- a/src/.vuepress/plugins/openApi.ts
+++ b/src/.vuepress/plugins/openApi.ts
@@ -1,29 +1,28 @@
-import fs from 'fs';
+import {parse as parseYaml} from 'yaml';
 import {createPage, type Plugin} from 'vuepress';
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import {kebabCase} from 'lodash-es';
 import {resolveRefs} from '../theme/client/utils/openApiHelpers';
 
 interface OpenApiPluginConfig {
-  specsDir: string;
+  yamlUrls: string[];
 }
 
 export const openApiPlugin = (config: OpenApiPluginConfig): Plugin => ({
   name: '@myparcel/vuepress-openapi',
-  onInitialized(app) {
-    // Find all .json files in config.spesDir and create a page for each of them
-    fs.readdir(config.specsDir, (err, files) => {
-      files.forEach(async (file) => {
-        // If the file is a .json file, create a page for it
-        if (file.endsWith('.json')) {
-          // Read the file and parse it as JSON
-          const spec = JSON.parse(fs.readFileSync(`${config.specsDir}/${file}`).toString()) as OpenApiType.Document;
-          // Use the basename of the file as the slug
-          const slug = file.replace('.json', '');
-          // Now generate the page contents
-          app.pages.push(
-            await createPage(app, {
-              path: `/api-reference/${slug}`,
-              content: `\
+  async onInitialized(app) {
+    // Find all yaml files in config.yamlUrls and create a page for each of them
+    await Promise.all(
+      config.yamlUrls?.map(async (url) => {
+        const spec = (await fetch(url).then(async (res) => parseYaml(await res.text()))) as OpenApiType.Document;
+        // Use the basename of the file as the slug
+        const slug = kebabCase(spec.info.title);
+
+        // Now generate the page contents
+        app.pages.push(
+          await createPage(app, {
+            path: `/api-reference/${slug}`,
+            content: `\
 ---
 title: ${spec.info.title}
 description: ${spec.info.description}
@@ -33,12 +32,11 @@ Version ${spec.info.version}
 ${spec.info.description ?? ''}
 
 ${renderChapters(spec)}
-          `,
-            }),
-          );
-        }
-      });
-    });
+                  `,
+          }),
+        );
+      }),
+    );
   },
 });
 
diff --git a/src/openapi/Petstore Expanded.json b/src/openapi/Petstore Expanded.json
deleted file mode 100644
index 420eede6..00000000
--- a/src/openapi/Petstore Expanded.json	
+++ /dev/null
@@ -1,242 +0,0 @@
-{
-  "openapi": "3.0.0",
-  "info": {
-    "version": "1.0.0",
-    "title": "Swagger Petstore",
-    "description": "A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification",
-    "termsOfService": "http://swagger.io/terms/",
-    "contact": {
-      "name": "Swagger API Team",
-      "email": "apiteam@swagger.io",
-      "url": "http://swagger.io"
-    },
-    "license": {
-      "name": "Apache 2.0",
-      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
-    }
-  },
-  "servers": [
-    {
-      "url": "https://petstore.swagger.io/v2"
-    }
-  ],
-  "paths": {
-    "/pets": {
-      "get": {
-        "description": "Returns all pets from the system that the user has access to\nNam sed condimentum est. Maecenas tempor sagittis sapien, nec rhoncus sem sagittis sit amet. Aenean at gravida augue, ac iaculis sem. Curabitur odio lorem, ornare eget elementum nec, cursus id lectus. Duis mi turpis, pulvinar ac eros ac, tincidunt varius justo. In hac habitasse platea dictumst. Integer at adipiscing ante, a sagittis ligula. Aenean pharetra tempor ante molestie imperdiet. Vivamus id aliquam diam. Cras quis velit non tortor eleifend sagittis. Praesent at enim pharetra urna volutpat venenatis eget eget mauris. In eleifend fermentum facilisis. Praesent enim enim, gravida ac sodales sed, placerat id erat. Suspendisse lacus dolor, consectetur non augue vel, vehicula interdum libero. Morbi euismod sagittis libero sed lacinia.\n\nSed tempus felis lobortis leo pulvinar rutrum. Nam mattis velit nisl, eu condimentum ligula luctus nec. Phasellus semper velit eget aliquet faucibus. In a mattis elit. Phasellus vel urna viverra, condimentum lorem id, rhoncus nibh. Ut pellentesque posuere elementum. Sed a varius odio. Morbi rhoncus ligula libero, vel eleifend nunc tristique vitae. Fusce et sem dui. Aenean nec scelerisque tortor. Fusce malesuada accumsan magna vel tempus. Quisque mollis felis eu dolor tristique, sit amet auctor felis gravida. Sed libero lorem, molestie sed nisl in, accumsan tempor nisi. Fusce sollicitudin massa ut lacinia mattis. Sed vel eleifend lorem. Pellentesque vitae felis pretium, pulvinar elit eu, euismod sapien.\n",
-        "operationId": "findPets",
-        "parameters": [
-          {
-            "name": "tags",
-            "in": "query",
-            "description": "tags to filter by",
-            "required": false,
-            "style": "form",
-            "schema": {
-              "type": "array",
-              "items": {
-                "type": "string"
-              }
-            }
-          },
-          {
-            "name": "limit",
-            "in": "query",
-            "description": "maximum number of results to return",
-            "required": false,
-            "schema": {
-              "type": "integer",
-              "format": "int32"
-            }
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "pet response",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/components/schemas/Pet"
-                  }
-                }
-              }
-            }
-          },
-          "default": {
-            "description": "unexpected error",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Error"
-                }
-              }
-            }
-          }
-        }
-      },
-      "post": {
-        "description": "Creates a new pet in the store. Duplicates are allowed",
-        "operationId": "addPet",
-        "requestBody": {
-          "description": "Pet to add to the store",
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/NewPet"
-              }
-            }
-          }
-        },
-        "responses": {
-          "200": {
-            "description": "pet response",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Pet"
-                }
-              }
-            }
-          },
-          "default": {
-            "description": "unexpected error",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Error"
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "/pets/{id}": {
-      "get": {
-        "description": "Returns a user based on a single ID, if the user does not have access to the pet",
-        "operationId": "find pet by id",
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "description": "ID of pet to fetch",
-            "required": true,
-            "schema": {
-              "type": "integer",
-              "format": "int64"
-            }
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "pet response",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Pet"
-                }
-              }
-            }
-          },
-          "default": {
-            "description": "unexpected error",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Error"
-                }
-              }
-            }
-          }
-        }
-      },
-      "delete": {
-        "description": "deletes a single pet based on the ID supplied",
-        "operationId": "deletePet",
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "description": "ID of pet to delete",
-            "required": true,
-            "schema": {
-              "type": "integer",
-              "format": "int64"
-            }
-          }
-        ],
-        "responses": {
-          "204": {
-            "description": "pet deleted"
-          },
-          "default": {
-            "description": "unexpected error",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Error"
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-  },
-  "components": {
-    "schemas": {
-      "Pet": {
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/NewPet"
-          },
-          {
-            "type": "object",
-            "required": [
-              "id"
-            ],
-            "properties": {
-              "id": {
-                "type": "integer",
-                "format": "int64"
-              }
-            }
-          }
-        ]
-      },
-      "NewPet": {
-        "type": "object",
-        "required": [
-          "name"
-        ],
-        "properties": {
-          "name": {
-            "type": "string"
-          },
-          "tag": {
-            "type": "string"
-          }
-        }
-      },
-      "Error": {
-        "type": "object",
-        "required": [
-          "code",
-          "message"
-        ],
-        "properties": {
-          "code": {
-            "type": "integer",
-            "format": "int32"
-          },
-          "message": {
-            "type": "string"
-          }
-        }
-      }
-    }
-  }
-}
\ No newline at end of file
diff --git a/src/openapi/callback-example.json b/src/openapi/callback-example.json
deleted file mode 100644
index 9a4df39b..00000000
--- a/src/openapi/callback-example.json
+++ /dev/null
@@ -1,84 +0,0 @@
-{
-  "openapi": "3.0.0",
-  "info": {
-    "title": "Callback Example",
-    "version": "1.0.0"
-  },
-  "paths": {
-    "/streams": {
-      "post": {
-        "description": "subscribes a client to receive out-of-band data",
-        "parameters": [
-          {
-            "name": "callbackUrl",
-            "in": "query",
-            "required": true,
-            "description": "the location where data will be sent.  Must be network accessible\nby the source server\n",
-            "schema": {
-              "type": "string",
-              "format": "uri",
-              "example": "https://tonys-server.com"
-            }
-          }
-        ],
-        "responses": {
-          "201": {
-            "description": "subscription successfully created",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "description": "subscription information",
-                  "required": [
-                    "subscriptionId"
-                  ],
-                  "properties": {
-                    "subscriptionId": {
-                      "description": "this unique identifier allows management of the subscription",
-                      "type": "string",
-                      "example": "2531329f-fb09-4ef7-887e-84e648214436"
-                    }
-                  }
-                }
-              }
-            }
-          }
-        },
-        "callbacks": {
-          "onData": {
-            "{$request.query.callbackUrl}/data": {
-              "post": {
-                "requestBody": {
-                  "description": "subscription payload",
-                  "content": {
-                    "application/json": {
-                      "schema": {
-                        "type": "object",
-                        "properties": {
-                          "timestamp": {
-                            "type": "string",
-                            "format": "date-time"
-                          },
-                          "userData": {
-                            "type": "string"
-                          }
-                        }
-                      }
-                    }
-                  }
-                },
-                "responses": {
-                  "202": {
-                    "description": "Your server implementation should return this HTTP status code\nif the data was received successfully\n"
-                  },
-                  "204": {
-                    "description": "Your server should return this HTTP status code if no longer interested\nin further updates\n"
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}
\ No newline at end of file
diff --git a/src/openapi/webhooks.json b/src/openapi/webhooks.json
deleted file mode 100644
index a7427522..00000000
--- a/src/openapi/webhooks.json
+++ /dev/null
@@ -1,331 +0,0 @@
-{
-    "openapi": "3.1.0",
-    "info": {
-        "title": "MyParcel Core-API",
-        "contact": {
-            "name": "IT Support",
-            "url": "support@myparcel.nl"
-        },
-        "version": "4.0.0"
-    },
-    "servers": [
-        {
-            "url": "https://api.myparcel.nl",
-            "description": "MyParcel Production Server"
-        }
-    ],
-    "paths": {
-        "/webhook_subscriptions": {
-            "get": {
-                "tags": [
-                    "Webhook Subscriptions"
-                ],
-                "description": "Show list of webhook subscriptions",
-                "operationId": "getSubscriptions",
-                "parameters": [
-                    {
-                        "$ref": "#/components/parameters/user_agent_header"
-                    },
-                    {
-                        "$ref": "#/components/parameters/account_id"
-                    },
-                    {
-                        "$ref": "#/components/parameters/shop_id"
-                    },
-                    {
-                        "name": "hook",
-                        "in": "query",
-                        "description": "The event from which you want to receive notifications",
-                        "required": false,
-                        "schema": {
-                            "description": "The event from which you want to receive notifications",
-                            "type": "string",
-                            "example": "shipment_status_change"
-                        }
-                    }
-                ],
-                "responses": {
-                    "200": {
-                        "description": "OK",
-                        "content": {
-                            "application/json; charset=utf-8": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/webhook_subscriptions_response"
-                                }
-                            }
-                        }
-                    },
-                    "400": {
-                        "description": "Validation error"
-                    },
-                    "401": {
-                        "description": "Unauthorized"
-                    },
-                    "403": {
-                        "description": "Forbidden"
-                    },
-                    "500": {
-                        "description": "Internal Server Error"
-                    }
-                },
-                "security": []
-            },
-            "post": {
-                "tags": [
-                    "Webhook Subscriptions"
-                ],
-                "description": "Add new webhook subscription.",
-                "operationId": "postSubscriptions",
-                "parameters": [
-                    {
-                        "$ref": "#/components/parameters/user_agent_header"
-                    }
-                ],
-                "requestBody": {
-                    "description": "| **Hook** | **Description** |\n|---- |------------|\n| `shipment_status_change` | Whenever the shipment_status of a shipment changes, this webhook will send you an update with the new value. We will not send an update with a status.|\n| `shipment_label_created` | When a label is created asynchronously (for example when creating shipments using accept header `application/vnd.shipment_label+json;charset=utf-8`), this webhook will send you a message with the URL of the label. |\n| `order_status_change` | Whenever the order_status of an order changes, this webhook will send you an update with the new value. |",
-                    "required": true,
-                    "content": {
-                        "application/json; charset=utf-8": {
-                            "schema": {
-                                "$ref": "#/components/schemas/webhook_subscription_request"
-                            }
-                        }
-                    }
-                },
-                "responses": {
-                    "201": {
-                        "description": "Response with array of webhook ids",
-                        "content": {
-                            "application/json; charset=utf-8": {
-                                "example": {
-                                    "data": {
-                                        "webhook_subscriptions": [
-                                            {
-                                                "id": 1
-                                            }
-                                        ]
-                                    }
-                                }
-                            }
-                        }
-                    },
-                    "400": {
-                        "description": "Validation error"
-                    },
-                    "401": {
-                        "description": "Unauthorized"
-                    },
-                    "403": {
-                        "description": "Forbidden"
-                    },
-                    "500": {
-                        "description": "Internal Server Error"
-                    }
-                },
-                "security": []
-            }
-        },
-        "/webhook_subscriptions/{webhook_subscriptions_id}": {
-            "delete": {
-                "tags": [
-                    "Webhook Subscriptions"
-                ],
-                "summary": "Delete webhook subscriptions.",
-                "description": "Delete a webhook subscription",
-                "operationId": "deleteSubscriptions",
-                "parameters": [
-                    {
-                        "$ref": "#/components/parameters/user_agent_header"
-                    },
-                    {
-                        "$ref": "#/components/parameters/webhook_subscriptions_id_in_path"
-                    }
-                ],
-                "responses": {
-                    "204": {
-                        "description": "No content"
-                    },
-                    "401": {
-                        "description": "Unauthorized"
-                    },
-                    "403": {
-                        "description": "Forbidden"
-                    },
-                    "500": {
-                        "description": "Internal Server Error"
-                    }
-                },
-                "security": []
-            }
-        }
-    },
-    "components": {
-        "schemas": {
-            "webhook_subscriptions_response": {
-                "required": [
-                    "data"
-                ],
-                "properties": {
-                    "data": {
-                        "required": [
-                            "webhook_subscriptions"
-                        ],
-                        "properties": {
-                            "webhook_subscriptions": {
-                                "type": "array",
-                                "items": {
-                                    "$ref": "#/components/schemas/webhook_subscription"
-                                }
-                            }
-                        },
-                        "type": "object"
-                    }
-                },
-                "type": "object"
-            },
-            "webhook_subscription": {
-                "description": "Webhook subscription",
-                "required": [
-                    "id",
-                    "account_id",
-                    "shop_id",
-                    "hook",
-                    "url"
-                ],
-                "properties": {
-                    "id": {
-                        "description": "ID of webhook subscriptions",
-                        "type": "integer",
-                        "format": "int32",
-                        "example": 56123456
-                    },
-                    "account_id": {
-                        "description": "Account ID",
-                        "type": "integer",
-                        "format": "int32",
-                        "example": 125678
-                    },
-                    "shop_id": {
-                        "description": "Shop ID",
-                        "type": "integer",
-                        "format": "int32",
-                        "example": 1234
-                    },
-                    "hook": {
-                        "description": "The event from which you want to receive notifications",
-                        "type": "string",
-                        "example": "shipment_status_changed"
-                    },
-                    "url": {
-                        "description": "The callback URL on which to receive notifications",
-                        "type": "string",
-                        "format": "uri",
-                        "example": "https://example.com/webhook"
-                    }
-                },
-                "type": "object"
-            },
-            "webhook_subscription_request": {
-                "description": "Webhook subscription request",
-                "required": [
-                    "data"
-                ],
-                "properties": {
-                    "data": {
-                        "required": [
-                            "webhook_subscription"
-                        ],
-                        "properties": {
-                            "webhook_subscription": {
-                                "required": [
-                                    "hook",
-                                    "url"
-                                ],
-                                "properties": {
-                                    "hook": {
-                                        "description": "The event from which you want to receive notifications",
-                                        "type": "string",
-                                        "example": "shipment_status_changed"
-                                    },
-                                    "url": {
-                                        "description": "The callback URL on which to receive notifications",
-                                        "type": "string",
-                                        "format": "uri",
-                                        "example": "https://example.com/webhook"
-                                    }
-                                },
-                                "type": "object"
-                            }
-                        },
-                        "type": "object"
-                    }
-                },
-                "type": "object"
-            }
-        },
-        "parameters": {
-            "account_id": {
-                "name": "account_id",
-                "in": "query",
-                "description": "The ID of the account.",
-                "required": false,
-                "schema": {
-                    "type": "integer",
-                    "format": "int32"
-                },
-                "example": "123456"
-            },
-            "shop_id": {
-                "name": "shop_id",
-                "in": "query",
-                "description": "The ID of the shop.",
-                "required": false,
-                "schema": {
-                    "type": "integer",
-                    "format": "int32"
-                },
-                "example": "5678"
-            },
-            "user_agent_header": {
-                "name": "User-Agent",
-                "in": "header",
-                "description": "The User-Agent header",
-                "required": true,
-                "schema": {
-                    "type": "string"
-                },
-                "example": "NameOfMyApp/1.0.0 PHP/8.1.0"
-            },
-            "webhook_subscriptions_id_in_path": {
-                "name": "webhook_subscriptions_id",
-                "in": "path",
-                "description": "The ID of the webhook subscription",
-                "required": true,
-                "schema": {
-                    "type": "integer",
-                    "format": "int32"
-                },
-                "example": "123456789"
-            }
-        },
-        "securitySchemes": {
-            "bearerAuth": {
-                "type": "http",
-                "description": "BASE64 encoded ",
-                "name": "Authorization",
-                "in": "header",
-                "scheme": "bearer"
-            }
-        }
-    },
-    "tags": [
-        {
-            "name": "Pickup Locations",
-            "description": "All about Pickup Locations"
-        },
-        {
-            "name": "Webhook Subscriptions",
-            "description": "All about Webhooks"
-        }
-    ]
-}
diff --git a/yarn.lock b/yarn.lock
index 900e3b67..4892c7e1 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1016,6 +1016,7 @@ __metadata:
     vitest: ^0.34.6
     vue-recaptcha: ^2.0.2
     vuepress: 2.0.0-beta.67
+    yaml: ^2.4.1
   languageName: unknown
   linkType: soft
 
@@ -11275,6 +11276,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"yaml@npm:^2.4.1":
+  version: 2.4.1
+  resolution: "yaml@npm:2.4.1"
+  bin:
+    yaml: bin.mjs
+  checksum: 4c391d07a5d5e935e058babb71026c9cdc9a6fd889e35dd91b53cfb0a12691b67c6c5c740858e71345fef18cd9c13c554a6dda9196f59820d769d94041badb0b
+  languageName: node
+  linkType: hard
+
 "yargs-parser@npm:^20.2.2":
   version: 20.2.9
   resolution: "yargs-parser@npm:20.2.9"

From b799fc0d3a30d7dcbcfabaceac15491edfbbbe94 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Fri, 12 Apr 2024 15:04:05 +0200
Subject: [PATCH 21/41] feat(open-api): add and improve display of various
 schema requirements

INT-407
---
 .../components/global/OpenApiRequestParam.vue |  23 +---
 .../components/global/OpenApiSchema.vue       |  19 ++--
 .../components/global/OpenApiSchemaInfo.vue   | 100 +++++++++++++++---
 3 files changed, 104 insertions(+), 38 deletions(-)

diff --git a/src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue b/src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue
index 7f85105f..d7a22e9b 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue
@@ -27,7 +27,6 @@
       class="text-gray-500 text-sm"
       v-html="parameter.description" />
 
-    <!-- TODO use / create examples component! -->
     <OpenApiExample
       v-if="parameter.example"
       :example="parameter.example" />
@@ -42,28 +41,14 @@
     </div>
   </td>
 
-  <td>
-    <code>{{ parameter.in }}</code>
+  <td class="align-top">
+    <code v-if="parameter.in">{{ parameter.in }}</code>
   </td>
 
-  <td>
-    <div
-      v-if="parameter.style"
-      class="oapi-res-param__param">
+  <td class="align-top">
+    <div v-if="parameter.style">
       Style: <code>{{ parameter.style }}</code>
     </div>
-
-    <div
-      v-if="parameter.content"
-      class="oapi-res-param__content">
-      <div class="oapi-res-param__muted">Content:</div>
-      TODO : MEDIA TYPES
-      <!--
-        <OpenApiMediaTypes
-        :current-locale="currentLocale"
-        :data="parameter.content" />
-      -->
-    </div>
   </td>
 </template>
 
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSchema.vue b/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
index 91c81c5d..6e4c44d8 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
@@ -17,6 +17,7 @@
         <th>Name</th>
         <th v-if="anyPropertyHasNesting(schema.properties)">Content</th>
       </thead>
+
       <tbody>
         <tr
           v-for="(property, key) in schema.properties"
@@ -101,26 +102,32 @@
           title="Additonal properties" />
       </div>
 
+      <div v-if="schema.not">
+        <OpenApiSchema
+          :schema="schema.not"
+          title="Not" />
+      </div>
+
       <div v-if="schema.allOf">
-        <strong>All of:</strong>
+        <em>All of:</em>
         <div
-          v-for="(oneOf, index) in schema.allOf"
+          v-for="(item, index) in schema.allOf"
           :key="index"
           class="ml-3">
           <OpenApiSchema
-            :schema="oneOf"
+            :schema="item"
             :collapsible="false" />
         </div>
       </div>
 
       <div v-if="schema.oneOf">
-        <strong>One of:</strong>
+        <em>One of:</em>
         <div
-          v-for="(oneOf, index) in schema.oneOf"
+          v-for="(item, index) in schema.oneOf"
           :key="index"
           class="ml-3">
           <OpenApiSchema
-            :schema="oneOf"
+            :schema="item"
             :collapsible="false" />
         </div>
       </div>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
index a02deb5a..7b6b7eec 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
@@ -15,41 +15,115 @@
           <template v-if="schema.format">({{ schema.format }})</template>
       </pre>
 
-    <p
+    <Markdown
       v-if="schema && schema.description"
-      class="m-0 p-0 text-gray-500 text-sm">
-      {{ schema.description }}
-    </p>
+      :content="schema.description"
+      class="m-0 p-0 text-gray-500 text-sm" />
 
-    <template v-if="schema && schema.enum">
-      <strong class="text-sm">Enum:</strong>
-      <ul class="list-disc">
+    <div v-if="schema && schema.enum?.length">
+      <strong class="text-sm">Possible values:</strong>
+      <ul
+        v-if="schema.enum.length < 10"
+        class="columns-2 list-disc">
         <li
           v-for="(value, index) in schema.enum"
           :key="index">
-          {{ value }}
+          <code>{{ value }}</code>
         </li>
       </ul>
-    </template>
+      <details v-else>
+        <summary>View all</summary>
+        <ul class="columns-2 list-disc">
+          <li
+            v-for="(value, index) in schema.enum"
+            :key="index">
+            <code>{{ value }}</code>
+          </li>
+        </ul>
+      </details>
+    </div>
 
-    <template v-if="schema && schema.default">
+    <div v-if="schema && schema.default">
       <strong class="inline-block text-sm">Default:</strong>&nbsp;
       <code class="inline-block m-0 p-1 text-sm">{{ schema.default }}</code>
-    </template>
+    </div>
 
-    <template v-if="schema && schema.pattern">
+    <div v-if="schema && schema.pattern">
       <strong class="inline-block text-sm">Pattern:</strong>&nbsp;
       <code class="inline-block m-0 p-1 text-sm">{{ schema.pattern }}</code>
-    </template>
+    </div>
+
+    <div v-if="schema.externalDocs">
+      <Markdown
+        v-if="schema.externalDocs.description"
+        :content="schema.externalDocs.description" />
+      <a
+        :href="schema.externalDocs.url"
+        target="_blank"
+        rel="noopener"
+        >External documentation</a
+      >
+    </div>
+
+    <div v-if="schema.multipleOf !== undefined">
+      <strong class="inline-block text-sm">Multiple of:</strong> <code>{{ schema.multipleOf }}</code>
+    </div>
+
+    <div v-if="schema.maximum !== undefined">
+      <strong class="inline-block text-sm">Max:</strong
+      ><code>{{ schema.exclusiveMaximum ? '<' : '<=' }} {{ schema.maximum }}</code>
+    </div>
+
+    <div v-if="schema.minimum !== undefined">
+      <strong class="inline-block text-sm">Min:</strong
+      ><code>{{ schema.exclusiveMinimum ? '>' : '>=' }} {{ schema.minimum }}</code>
+    </div>
+
+    <div v-if="schema.maxLength !== undefined">
+      <strong class="inline-block text-sm">Max length:</strong> <code>{{ schema.maxLength }}</code>
+    </div>
+
+    <div v-if="schema.minLength !== undefined">
+      <strong class="inline-block text-sm">Min length:</strong> <code>{{ schema.minLength }}</code>
+    </div>
+
+    <div v-if="schema.maxItems !== undefined">
+      <strong class="inline-block text-sm">Max items:</strong> <code>{{ schema.maxItems }}</code>
+    </div>
+
+    <div v-if="schema.minItems !== undefined">
+      <strong class="inline-block text-sm">Min items:</strong> <code>{{ schema.minItems }}</code>
+    </div>
+
+    <div v-if="schema.maxProperties !== undefined">
+      <strong class="inline-block text-sm">Max properties:</strong> <code>{{ schema.maxProperties }}</code>
+    </div>
+
+    <div v-if="schema.minProperties !== undefined">
+      <strong class="inline-block text-sm">Min properties:</strong> <code>{{ schema.minProperties }}</code>
+    </div>
+
+    <div v-if="schema.additionalProperties !== undefined && typeof schema.additionalProperties === 'boolean'">
+      <strong class="inline-block text-sm">Additional properties:</strong>
+      <code>{{ !!schema.additionalProperties }}</code>
+    </div>
 
     <template v-if="schema.example">
       <OpenApiExample :example="schema.example" />
     </template>
+
+    <template v-if="schema.examples">
+      <OpenApiExample
+        v-for="(example, index) in schema.examples"
+        :key="index"
+        :example="example" />
+    </template>
   </header>
 </template>
 
 <script setup lang="ts">
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import {Markdown} from '@mptheme/client/components/global';
 import OpenApiExample from './OpenApiExample.vue';
 
 defineProps<{

From d7640b5d4856155b91f8cff7e925bf88a4b40395 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Fri, 12 Apr 2024 15:46:17 +0200
Subject: [PATCH 22/41] fix(open-api): add missing global components to the
 indexed list

INT-407
---
 src/.vuepress/theme/client/components/global/index.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/.vuepress/theme/client/components/global/index.ts b/src/.vuepress/theme/client/components/global/index.ts
index 910e65d5..c2ea9da2 100644
--- a/src/.vuepress/theme/client/components/global/index.ts
+++ b/src/.vuepress/theme/client/components/global/index.ts
@@ -67,6 +67,10 @@ export {default as OpenApi} from './OpenApi.vue';
 
 export {default as OpenApiExample} from './OpenApiExample.vue';
 
+export {default as OpenApiInfo} from './OpenApiInfo.vue';
+
+export {default as OpenApiOperation} from './OpenApiOperation.vue';
+
 export {default as OpenApiPath} from './OpenApiPath.vue';
 
 export {default as OpenApiRequestParam} from './OpenApiRequestParam.vue';

From e20531fa752c8142a03b690109b6607a729aaf56 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Fri, 12 Apr 2024 17:07:40 +0200
Subject: [PATCH 23/41] feat(open-api): add top-level security information

INT-407
---
 src/.vuepress/plugins/openApi.ts              | 12 ++++--
 .../global/OpenApiSecurityRequirements.vue    | 42 +++++++++++++++++++
 .../global/OpenApiSecurityScheme.vue          | 18 ++++++++
 .../theme/client/components/global/index.ts   |  4 ++
 4 files changed, 73 insertions(+), 3 deletions(-)
 create mode 100644 src/.vuepress/theme/client/components/global/OpenApiSecurityRequirements.vue
 create mode 100644 src/.vuepress/theme/client/components/global/OpenApiSecurityScheme.vue

diff --git a/src/.vuepress/plugins/openApi.ts b/src/.vuepress/plugins/openApi.ts
index eb0b73c7..43eae78c 100644
--- a/src/.vuepress/plugins/openApi.ts
+++ b/src/.vuepress/plugins/openApi.ts
@@ -31,7 +31,13 @@ Version ${spec.info.version}
 
 ${spec.info.description ?? ''}
 
-${renderChapters(spec)}
+## Authorization
+<OpenApiSecurityRequirements
+:security='${JSON.stringify(spec.security ?? [])}'
+:security-schemes='${JSON.stringify(spec.components?.securitySchemes ?? [])}' />
+
+## Endpoints
+${renderPaths(spec)}
                   `,
           }),
         );
@@ -40,7 +46,7 @@ ${renderChapters(spec)}
   },
 });
 
-function renderChapters(document: OpenApiType.Document): string {
+function renderPaths(document: OpenApiType.Document): string {
   const resolvedDocument = resolveRefs(document);
 
   let chapters = '';
@@ -48,7 +54,7 @@ function renderChapters(document: OpenApiType.Document): string {
   if (resolvedDocument.paths) {
     for (const [path, pathObj] of Object.entries(resolvedDocument.paths)) {
       chapters += `
-## ${path}
+### ${path}
 \n
 <OpenApiPath :path='${JSON.stringify(pathObj)}' title='${path}' />
     `;
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSecurityRequirements.vue b/src/.vuepress/theme/client/components/global/OpenApiSecurityRequirements.vue
new file mode 100644
index 00000000..a209c6c7
--- /dev/null
+++ b/src/.vuepress/theme/client/components/global/OpenApiSecurityRequirements.vue
@@ -0,0 +1,42 @@
+<template>
+  <div v-if="resolvedSchemes?.length">
+    <ul>
+      <OpenApiSecurityScheme
+        v-for="(securityItem, index) in resolvedSchemes"
+        :key="index"
+        :scheme="resolveRequirementToScheme(securityItem)" />
+    </ul>
+  </div>
+</template>
+
+<script setup lang="ts">
+import {computed} from 'vue';
+import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import {OpenApiSecurityScheme} from '@mptheme/client/components/global';
+
+const props = defineProps<{
+  security: OpenApiType.SecurityRequirementObject[];
+  securitySchemes: Record<string, OpenApiType.SecuritySchemeObject>;
+}>();
+
+const resolvedSchemes = computed(() => {
+  const resolved: OpenApiType.SecurityRequirementObject[] = [];
+
+  for (const requirement of props.security) {
+    const scheme = resolveRequirementToScheme(requirement);
+
+    if (scheme) {
+      resolved.push(requirement);
+    }
+  }
+
+  return resolved;
+});
+
+function resolveRequirementToScheme(
+  requirement: OpenApiType.SecurityRequirementObject,
+): OpenApiType.SecuritySchemeObject | undefined {
+  // Find the securityScheme with the same key as the securityRequirement
+  return props.securitySchemes[Object.keys(requirement)[0]];
+}
+</script>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSecurityScheme.vue b/src/.vuepress/theme/client/components/global/OpenApiSecurityScheme.vue
new file mode 100644
index 00000000..ec3176d7
--- /dev/null
+++ b/src/.vuepress/theme/client/components/global/OpenApiSecurityScheme.vue
@@ -0,0 +1,18 @@
+<template>
+  <li v-if="scheme.type === 'apiKey'">
+    <strong>API Key</strong><br />
+    <code class="m-0 p-0 text-sm whitespace-nowrap"> {{ scheme.in }}: {{ scheme.name }} </code>
+  </li>
+  <li v-else-if="scheme.type === 'http'">
+    <strong>HTTP</strong><br />
+    <code class="m-0 p-0 text-sm whitespace-nowrap"> {{ scheme.scheme }}: {{ scheme.bearerFormat }} </code>
+  </li>
+</template>
+
+<script setup lang="ts">
+import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+
+defineProps<{
+  scheme: OpenApiType.SecuritySchemeObject;
+}>();
+</script>
diff --git a/src/.vuepress/theme/client/components/global/index.ts b/src/.vuepress/theme/client/components/global/index.ts
index c2ea9da2..a7cc79f6 100644
--- a/src/.vuepress/theme/client/components/global/index.ts
+++ b/src/.vuepress/theme/client/components/global/index.ts
@@ -80,3 +80,7 @@ export {default as OpenApiResponses} from './OpenApiResponses.vue';
 export {default as OpenApiSchema} from './OpenApiSchema.vue';
 
 export {default as OpenApiSchemaInfo} from './OpenApiSchemaInfo.vue';
+
+export {default as OpenApiSecurityRequirements} from './OpenApiSecurityRequirements.vue';
+
+export {default as OpenApiSecurityScheme} from './OpenApiSecurityScheme.vue';

From 4697710a6292605d196989850fd59f1f3dbcc247 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Mon, 15 Apr 2024 14:45:03 +0200
Subject: [PATCH 24/41] fix(open-api): fix example rendering "value" key if
 summary or description not set

---
 .../components/global/OpenApiExample.vue      | 32 +++++++------------
 .../components/global/OpenApiResponses.vue    | 25 ++++-----------
 2 files changed, 18 insertions(+), 39 deletions(-)

diff --git a/src/.vuepress/theme/client/components/global/OpenApiExample.vue b/src/.vuepress/theme/client/components/global/OpenApiExample.vue
index 36e40aa2..0086ba2b 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiExample.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiExample.vue
@@ -1,34 +1,28 @@
 <template>
   <template v-if="example">
     <strong class="inline-block text-sm">{{ title || 'Example' }}:</strong>&nbsp;
-    <p
+    <Markdown
       v-if="isExampleObject(example) && example.summary"
-      class="text-sm">
-      {{ example.summary }}
-    </p>
+      class="text-sm"
+      :content="example.summary" />
 
-    <div
+    <Markdown
       v-if="isExampleObject(example) && example.description"
       class="text-sm"
-      v-html="example.description" />
+      :content="example.description" />
+
+    <CodeBlock
+      v-if="formattedExample && isMultilineString"
+      :code="formattedExample" />
 
-    <template v-if="formattedExample">
-      <CodeBlock
-        v-if="isMultilineString"
-        :code="formattedExample"
-        language="json" />
-      <code
-        v-else
-        class="inline-block m-0 p-1 text-sm"
-        >{{ formattedExample }}</code
-      >
-    </template>
+    <code v-else>{{ formattedExample }}</code>
   </template>
 </template>
 
 <script setup lang="ts">
 import {computed} from 'vue';
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import Markdown from '@mptheme/client/components/global/Markdown.vue';
 import CodeBlock from './CodeBlock.vue';
 
 const props = defineProps<{
@@ -57,8 +51,6 @@ function formatExample(example: unknown): string {
 
 // Guard to check if example is an Example object
 const isExampleObject = (example: unknown): example is OpenApiType.ExampleObject => {
-  return (
-    !!example && typeof example === 'object' && 'summary' in example && 'description' in example && 'value' in example
-  );
+  return !!example && typeof example === 'object' && 'value' in example;
 };
 </script>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
index d7efaa44..0570c252 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
@@ -29,15 +29,7 @@
             :key="`example${type}`"
             title="Example response"
             tag="strong">
-            <CodeGroup
-              :items="[
-                {
-                  title: type.toString(),
-                  code: JSON.stringify(item.example),
-                  language: 'json',
-                },
-              ]">
-            </CodeGroup>
+            <OpenApiExample :example="item.example" />
           </DetailsExpand>
 
           <DetailsExpand
@@ -45,16 +37,10 @@
             :key="`examples${type}`"
             title="Example responses"
             tag="strong">
-            <CodeGroup
-              v-if="'examples' in item && Object.entries(item.examples)?.length"
-              :items="
-                Object.entries(item.examples).map(([key, value]) => ({
-                  title: key,
-                  code: JSON.stringify(value),
-                  language: 'json',
-                }))
-              ">
-            </CodeGroup>
+            <OpenApiExample
+              v-for="(example, index) in item.examples"
+              :key="index"
+              :example="example" />
           </DetailsExpand>
         </template>
       </li>
@@ -67,6 +53,7 @@ import {computed, type ComputedRef} from 'vue';
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
 import {isReponseObject} from '@mptheme/client/utils/openApiGuards';
 import OpenApiSchema from './OpenApiSchema.vue';
+import OpenApiExample from './OpenApiExample.vue';
 import Http from './Http.vue';
 import DetailsExpand from './DetailsExpand.vue';
 import CodeGroup from './CodeGroup.vue';

From 0cb20353cacf527f98394e2705ec45bb1ad419af Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Mon, 15 Apr 2024 15:25:26 +0200
Subject: [PATCH 25/41] fix(open-api): don't show "Authorization" heading
 without any security config

---
 src/.vuepress/plugins/openApi.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/.vuepress/plugins/openApi.ts b/src/.vuepress/plugins/openApi.ts
index 43eae78c..35a96e86 100644
--- a/src/.vuepress/plugins/openApi.ts
+++ b/src/.vuepress/plugins/openApi.ts
@@ -31,7 +31,7 @@ Version ${spec.info.version}
 
 ${spec.info.description ?? ''}
 
-## Authorization
+${spec.security ? '## Authorization' : ''}
 <OpenApiSecurityRequirements
 :security='${JSON.stringify(spec.security ?? [])}'
 :security-schemes='${JSON.stringify(spec.components?.securitySchemes ?? [])}' />

From a241ae75f497ef3047f7f98eb5ceb6b0528ced9d Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Mon, 15 Apr 2024 16:07:35 +0200
Subject: [PATCH 26/41] feat(open-api): add auth/security requirements for
 individual operations

INT-407
---
 src/.vuepress/plugins/openApi.ts                     |  2 +-
 .../theme/client/components/global/OpenApi.vue       |  1 +
 .../client/components/global/OpenApiOperation.vue    | 12 +++++++++---
 .../theme/client/components/global/OpenApiPath.vue   |  4 +++-
 .../global/OpenApiSecurityRequirements.vue           |  6 +++---
 .../components/global/OpenApiSecurityScheme.vue      |  9 +++++++++
 6 files changed, 26 insertions(+), 8 deletions(-)

diff --git a/src/.vuepress/plugins/openApi.ts b/src/.vuepress/plugins/openApi.ts
index 35a96e86..129a5fd8 100644
--- a/src/.vuepress/plugins/openApi.ts
+++ b/src/.vuepress/plugins/openApi.ts
@@ -56,7 +56,7 @@ function renderPaths(document: OpenApiType.Document): string {
       chapters += `
 ### ${path}
 \n
-<OpenApiPath :path='${JSON.stringify(pathObj)}' title='${path}' />
+<OpenApiPath :path='${JSON.stringify(pathObj)}' :components='${JSON.stringify(document.components)}' title='${path}' />
     `;
     }
   }
diff --git a/src/.vuepress/theme/client/components/global/OpenApi.vue b/src/.vuepress/theme/client/components/global/OpenApi.vue
index 0eb6c491..2ca27d0b 100644
--- a/src/.vuepress/theme/client/components/global/OpenApi.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApi.vue
@@ -8,6 +8,7 @@
       <OpenApiPath
         v-if="item"
         :path="item"
+        :components="document.components"
         :title="path" />
     </article>
   </section>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiOperation.vue b/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
index 75dbf8e6..fc70a3c9 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
@@ -8,9 +8,13 @@
     >
     <pre class="dark:text-gray-100 inline m-0 ml-2 p-0 text-gray-700 text-sm">{{ endpoint }}</pre>
     <br />
-    <template v-if="authentication?.length">
+
+    <template v-if="securityRequirements?.length && securitySchemes">
       <strong>Authentication:</strong>&nbsp;
-      <pre>{{ authentication }}</pre>
+      <OpenApiSecurityRequirements
+        class="text-sm"
+        :security="securityRequirements"
+        :security-schemes="securitySchemes" />
     </template>
   </header>
 </template>
@@ -18,11 +22,13 @@
 <script setup lang="ts">
 import {computed} from 'vue';
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import OpenApiSecurityRequirements from '@mptheme/client/components/global/OpenApiSecurityRequirements.vue';
 
 const props = defineProps<{
   method: string;
   endpoint: string;
-  authentication?: OpenApiType.SecurityRequirementObject[] | null;
+  securityRequirements?: OpenApiType.SecurityRequirementObject[];
+  securitySchemes?: Record<string, OpenApiType.SecuritySchemeObject>;
 }>();
 
 const methodClass = computed(() => {
diff --git a/src/.vuepress/theme/client/components/global/OpenApiPath.vue b/src/.vuepress/theme/client/components/global/OpenApiPath.vue
index 4c1548a1..0815483f 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiPath.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiPath.vue
@@ -13,7 +13,8 @@
         <OpenApiOperation
           :method="method"
           :endpoint="title"
-          :authentication="'security' in operation ? operation.security : null" />
+          :security-schemes="components?.securitySchemes as Record<string, OpenApiType.SecuritySchemeObject>"
+          :security-requirements="'security' in operation ? operation.security : undefined" />
 
         <p v-if="'description' in operation">{{ operation.description }}</p>
 
@@ -76,5 +77,6 @@ import DetailsExpand from './DetailsExpand.vue';
 defineProps<{
   title: string;
   path: OpenApiType.PathItemObject;
+  components?: OpenApiType.ComponentsObject;
 }>();
 </script>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSecurityRequirements.vue b/src/.vuepress/theme/client/components/global/OpenApiSecurityRequirements.vue
index a209c6c7..b23bd6b6 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiSecurityRequirements.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiSecurityRequirements.vue
@@ -4,7 +4,7 @@
       <OpenApiSecurityScheme
         v-for="(securityItem, index) in resolvedSchemes"
         :key="index"
-        :scheme="resolveRequirementToScheme(securityItem)" />
+        :scheme="securityItem" />
     </ul>
   </div>
 </template>
@@ -20,13 +20,13 @@ const props = defineProps<{
 }>();
 
 const resolvedSchemes = computed(() => {
-  const resolved: OpenApiType.SecurityRequirementObject[] = [];
+  const resolved: OpenApiType.SecuritySchemeObject[] = [];
 
   for (const requirement of props.security) {
     const scheme = resolveRequirementToScheme(requirement);
 
     if (scheme) {
-      resolved.push(requirement);
+      resolved.push(scheme);
     }
   }
 
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSecurityScheme.vue b/src/.vuepress/theme/client/components/global/OpenApiSecurityScheme.vue
index ec3176d7..97658281 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiSecurityScheme.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiSecurityScheme.vue
@@ -2,15 +2,24 @@
   <li v-if="scheme.type === 'apiKey'">
     <strong>API Key</strong><br />
     <code class="m-0 p-0 text-sm whitespace-nowrap"> {{ scheme.in }}: {{ scheme.name }} </code>
+    <Markdown
+      v-if="scheme.description"
+      class="m-0 p-0 text-gray-600 text-sm"
+      :content="scheme.description" />
   </li>
   <li v-else-if="scheme.type === 'http'">
     <strong>HTTP</strong><br />
     <code class="m-0 p-0 text-sm whitespace-nowrap"> {{ scheme.scheme }}: {{ scheme.bearerFormat }} </code>
+    <Markdown
+      v-if="scheme.description"
+      class="m-0 p-0 text-gray-600 text-sm"
+      :content="scheme.description" />
   </li>
 </template>
 
 <script setup lang="ts">
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import Markdown from '@mptheme/client/components/global/Markdown.vue';
 
 defineProps<{
   scheme: OpenApiType.SecuritySchemeObject;

From 6b1e0be56d3be61c9d3f9189cefd81288b96bd72 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Mon, 15 Apr 2024 16:36:13 +0200
Subject: [PATCH 27/41] feat(open-api): support display of webhooks and make
 paths optional

INT-407
---
 src/.vuepress/plugins/openApi.ts | 61 +++++++++++++++++---------------
 1 file changed, 33 insertions(+), 28 deletions(-)

diff --git a/src/.vuepress/plugins/openApi.ts b/src/.vuepress/plugins/openApi.ts
index 129a5fd8..4e8ac495 100644
--- a/src/.vuepress/plugins/openApi.ts
+++ b/src/.vuepress/plugins/openApi.ts
@@ -14,51 +14,56 @@ export const openApiPlugin = (config: OpenApiPluginConfig): Plugin => ({
     // Find all yaml files in config.yamlUrls and create a page for each of them
     await Promise.all(
       config.yamlUrls?.map(async (url) => {
-        const spec = (await fetch(url).then(async (res) => parseYaml(await res.text()))) as OpenApiType.Document;
+        const document = (await fetch(url).then(async (res) => parseYaml(await res.text()))) as OpenApiType.Document;
         // Use the basename of the file as the slug
-        const slug = kebabCase(spec.info.title);
+        const resolvedDocument = resolveRefs(document);
 
         // Now generate the page contents
-        app.pages.push(
-          await createPage(app, {
-            path: `/api-reference/${slug}`,
-            content: `\
+        app.pages.push(await createPage(app, generateOpenApiPage(resolvedDocument)));
+      }),
+    );
+  },
+});
+
+function generateOpenApiPage(document: OpenApiType.Document) {
+  return {
+    path: `/api-reference/${kebabCase(document.info.title)}`,
+    content: `\
 ---
-title: ${spec.info.title}
-description: ${spec.info.description}
+title: ${document.info.title}
+description: ${document.info.description}
 ---
-Version ${spec.info.version}
+Version ${document.info.version}
 
-${spec.info.description ?? ''}
+${document.info.description ?? ''}
 
-${spec.security ? '## Authorization' : ''}
+${document.security ? '## Authorization' : ''}
 <OpenApiSecurityRequirements
-:security='${JSON.stringify(spec.security ?? [])}'
-:security-schemes='${JSON.stringify(spec.components?.securitySchemes ?? [])}' />
+:security='${JSON.stringify(document.security ?? [])}'
+:security-schemes='${JSON.stringify(document.components?.securitySchemes ?? [])}' />
+
+${renderPaths(document, document.paths, 'Endpoints')}
 
-## Endpoints
-${renderPaths(spec)}
+${renderPaths(document, document.webhooks, 'Webhooks')}
                   `,
-          }),
-        );
-      }),
-    );
-  },
-});
+  };
+}
 
-function renderPaths(document: OpenApiType.Document): string {
-  const resolvedDocument = resolveRefs(document);
+function renderPaths(
+  document: OpenApiType.Document,
+  paths: OpenApiType.PathsObject | undefined,
+  heading: string,
+): string {
+  if (!paths || !Object.keys(paths).length) return '';
 
-  let chapters = '';
+  let chapters = `## ${heading}`;
 
-  if (resolvedDocument.paths) {
-    for (const [path, pathObj] of Object.entries(resolvedDocument.paths)) {
-      chapters += `
+  for (const [path, pathObj] of Object.entries(paths)) {
+    chapters += `
 ### ${path}
 \n
 <OpenApiPath :path='${JSON.stringify(pathObj)}' :components='${JSON.stringify(document.components)}' title='${path}' />
     `;
-    }
   }
 
   return chapters;

From 5d50d1f5a6812d144a3488ab8ee84d71774dacf3 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Mon, 15 Apr 2024 16:49:51 +0200
Subject: [PATCH 28/41] ci(open-api): add nightly (re)deploy to update with
 changes from remote openapi documents

INT-407
---
 .github/workflows/nightly-rebuild.yml | 34 +++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)
 create mode 100644 .github/workflows/nightly-rebuild.yml

diff --git a/.github/workflows/nightly-rebuild.yml b/.github/workflows/nightly-rebuild.yml
new file mode 100644
index 00000000..9fe0da14
--- /dev/null
+++ b/.github/workflows/nightly-rebuild.yml
@@ -0,0 +1,34 @@
+name: 'Nightly rebuild 🌙'
+
+on:
+  schedule:
+    - cron: '0 0 * * *'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  upload:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: ./.github/actions/build
+
+      - uses: actions/upload-pages-artifact@v1
+        with:
+          path: src/.vuepress/dist
+
+  deploy-ghp:
+    needs: upload
+    runs-on: ubuntu-22.04
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v1

From 92ec5d9d06367bb35389cf89eb6cc98c2e3b7500 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Tue, 16 Apr 2024 12:29:30 +0200
Subject: [PATCH 29/41] feat(open-api): add servers display if set

INT-407
---
 src/.vuepress/plugins/openApi.ts              |  3 +++
 .../components/global/OpenApiServers.vue      | 23 +++++++++++++++++++
 .../theme/client/components/global/index.ts   |  2 ++
 3 files changed, 28 insertions(+)
 create mode 100644 src/.vuepress/theme/client/components/global/OpenApiServers.vue

diff --git a/src/.vuepress/plugins/openApi.ts b/src/.vuepress/plugins/openApi.ts
index 4e8ac495..c507b63a 100644
--- a/src/.vuepress/plugins/openApi.ts
+++ b/src/.vuepress/plugins/openApi.ts
@@ -42,6 +42,9 @@ ${document.security ? '## Authorization' : ''}
 :security='${JSON.stringify(document.security ?? [])}'
 :security-schemes='${JSON.stringify(document.components?.securitySchemes ?? [])}' />
 
+${document.servers?.length ? '## Servers' : ''}
+<OpenApiServers :servers='${JSON.stringify(document.servers ?? [])}' />
+
 ${renderPaths(document, document.paths, 'Endpoints')}
 
 ${renderPaths(document, document.webhooks, 'Webhooks')}
diff --git a/src/.vuepress/theme/client/components/global/OpenApiServers.vue b/src/.vuepress/theme/client/components/global/OpenApiServers.vue
new file mode 100644
index 00000000..a383c95b
--- /dev/null
+++ b/src/.vuepress/theme/client/components/global/OpenApiServers.vue
@@ -0,0 +1,23 @@
+<template>
+  <ul
+    v-if="servers?.length"
+    class="open-api-servers">
+    <li
+      v-for="(server, index) in servers"
+      :key="index">
+      <code>{{ server.url }}</code>
+      <Markdown
+        v-if="server.description"
+        :content="server.description" />
+    </li>
+  </ul>
+</template>
+
+<script setup lang="ts">
+import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import Markdown from './Markdown.vue';
+
+defineProps<{
+  servers: OpenApiType.Document['servers'];
+}>();
+</script>
diff --git a/src/.vuepress/theme/client/components/global/index.ts b/src/.vuepress/theme/client/components/global/index.ts
index a7cc79f6..13b4a70c 100644
--- a/src/.vuepress/theme/client/components/global/index.ts
+++ b/src/.vuepress/theme/client/components/global/index.ts
@@ -84,3 +84,5 @@ export {default as OpenApiSchemaInfo} from './OpenApiSchemaInfo.vue';
 export {default as OpenApiSecurityRequirements} from './OpenApiSecurityRequirements.vue';
 
 export {default as OpenApiSecurityScheme} from './OpenApiSecurityScheme.vue';
+
+export {default as OpenApiServers} from './OpenApiServers.vue';

From 7cd4a3c790051555833d399f3b244ccec89d3da7 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Tue, 16 Apr 2024 12:49:27 +0200
Subject: [PATCH 30/41] fix(open-api): render all description fields as
 markdown

INT-407
---
 .../theme/client/components/global/OpenApiInfo.vue     |  5 ++++-
 .../theme/client/components/global/OpenApiPath.vue     |  4 +++-
 .../client/components/global/OpenApiRequestParam.vue   |  7 +++----
 .../client/components/global/OpenApiResponses.vue      | 10 +++++-----
 4 files changed, 15 insertions(+), 11 deletions(-)

diff --git a/src/.vuepress/theme/client/components/global/OpenApiInfo.vue b/src/.vuepress/theme/client/components/global/OpenApiInfo.vue
index 419e98b0..fb2ca7e6 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiInfo.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiInfo.vue
@@ -3,13 +3,16 @@
     <hgroup>
       <h2>{{ info.title }}</h2>
       <p>(v{{ info.version }})</p>
-      <p v-if="info.description">{{ info.description }}</p>
+      <Markdown
+        v-if="info.description"
+        :content="info.description" />
     </hgroup>
   </section>
 </template>
 
 <script setup lang="ts">
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import Markdown from './Markdown.vue';
 
 defineProps<{
   info: OpenApiType.Document['info'];
diff --git a/src/.vuepress/theme/client/components/global/OpenApiPath.vue b/src/.vuepress/theme/client/components/global/OpenApiPath.vue
index 0815483f..cba1933b 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiPath.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiPath.vue
@@ -16,7 +16,9 @@
           :security-schemes="components?.securitySchemes as Record<string, OpenApiType.SecuritySchemeObject>"
           :security-requirements="'security' in operation ? operation.security : undefined" />
 
-        <p v-if="'description' in operation">{{ operation.description }}</p>
+        <Markdown
+          v-if="'description' in operation && operation.description?.length"
+          :content="operation.description" />
 
         <template v-if="'parameters' in operation">
           <h4>Request parameters</h4>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue b/src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue
index d7a22e9b..b517fe4a 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue
@@ -19,13 +19,13 @@
       v-if="parameter.schema"
       :schema="parameter.schema" />
 
-    <div
+    <Markdown
       v-if="
         parameter.description &&
         !(parameter.schema && 'description' in parameter.schema && parameter.schema.description?.length)
       "
       class="text-gray-500 text-sm"
-      v-html="parameter.description" />
+      :content="parameter.description" />
 
     <OpenApiExample
       v-if="parameter.example"
@@ -56,9 +56,8 @@
 import {computed, defineProps} from 'vue';
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
 import OpenApiSchema from './OpenApiSchema.vue';
-// import OpenApiObjectModel from './OpenApiObjectModel.vue';
-// import OpenApiMediaTypes from './OpenApiMediaTypes.vue';
 import OpenApiExample from './OpenApiExample.vue';
+import Markdown from './Markdown.vue';
 
 const props = defineProps<{
   parameter: OpenApiType.ParameterObject;
diff --git a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
index 0570c252..dd5590e6 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
@@ -7,11 +7,11 @@
         :key="code"
         class="m-0 p-0">
         <Http :code="code" />
-        <p
+
+        <Markdown
           v-if="response.description"
-          class="text-gray-500 text-sm">
-          {{ response.description }}
-        </p>
+          class="text-gray-500 text-sm"
+          :content="response.description" />
 
         <template v-for="(item, type) in response.content">
           <DetailsExpand
@@ -54,9 +54,9 @@ import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
 import {isReponseObject} from '@mptheme/client/utils/openApiGuards';
 import OpenApiSchema from './OpenApiSchema.vue';
 import OpenApiExample from './OpenApiExample.vue';
+import Markdown from './Markdown.vue';
 import Http from './Http.vue';
 import DetailsExpand from './DetailsExpand.vue';
-import CodeGroup from './CodeGroup.vue';
 
 const props = defineProps<{
   responses: OpenApiType.ResponsesObject;

From ddcf197d318e4b5753e18d6fb487305588009ad6 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Tue, 16 Apr 2024 12:56:04 +0200
Subject: [PATCH 31/41] docs(open-api): remove all unpublishable schemas

---
 src/.vuepress/config.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/.vuepress/config.ts b/src/.vuepress/config.ts
index 3e14f36b..2c88dd41 100755
--- a/src/.vuepress/config.ts
+++ b/src/.vuepress/config.ts
@@ -27,7 +27,7 @@ export default defineUserConfig({
 
   plugins: [
     openApiPlugin({
-      yamlUrls: ['https://address.api.myparcel.nl/openapi.yaml'],
+      yamlUrls: [],
     }),
 
     parseTranslationsPlugin({

From 7c7dfdc8ffae7074b58700846f55a33f28ebd265 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Fri, 19 Apr 2024 14:22:38 +0200
Subject: [PATCH 32/41] style(open-api): clean up formatting

---
 .../theme/client/components/global/OpenApiOperation.vue     | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/.vuepress/theme/client/components/global/OpenApiOperation.vue b/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
index fc70a3c9..ecf5654d 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
@@ -3,9 +3,9 @@
     <strong>Endpoint:</strong>
     <pre
       class="dark:text-black inline-block leading-none m-0 ml-3 p-1 rounded-sm text-sm"
-      :class="methodClass"
-      >{{ method.toUpperCase() }}</pre
-    >
+      :class="methodClass">
+      {{ method.toUpperCase() }}
+    </pre>
     <pre class="dark:text-gray-100 inline m-0 ml-2 p-0 text-gray-700 text-sm">{{ endpoint }}</pre>
     <br />
 

From a126501f0ce440ce1fceff5e1a9986032de4ea14 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Fri, 19 Apr 2024 14:34:53 +0200
Subject: [PATCH 33/41] refactor(open-api): add type definition to method prop
 for `OpenApiOperation` component

---
 .../theme/client/components/global/OpenApiOperation.vue         | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/.vuepress/theme/client/components/global/OpenApiOperation.vue b/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
index ecf5654d..1619312d 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
@@ -25,7 +25,7 @@ import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
 import OpenApiSecurityRequirements from '@mptheme/client/components/global/OpenApiSecurityRequirements.vue';
 
 const props = defineProps<{
-  method: string;
+  method: OpenApiType.HttpMethods;
   endpoint: string;
   securityRequirements?: OpenApiType.SecurityRequirementObject[];
   securitySchemes?: Record<string, OpenApiType.SecuritySchemeObject>;

From 2b71469bb31ab00261a05dd51bffed3929def4f1 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Fri, 19 Apr 2024 15:00:29 +0200
Subject: [PATCH 34/41] refactor(open-api): don't use indexes for keys

---
 .../client/components/global/OpenApiPath.vue  |  4 ++--
 .../components/global/OpenApiSchema.vue       | 20 +++++++++----------
 .../components/global/OpenApiSchemaInfo.vue   | 12 +++++------
 .../global/OpenApiSecurityRequirements.vue    |  8 ++++----
 4 files changed, 22 insertions(+), 22 deletions(-)

diff --git a/src/.vuepress/theme/client/components/global/OpenApiPath.vue b/src/.vuepress/theme/client/components/global/OpenApiPath.vue
index cba1933b..08877e25 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiPath.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiPath.vue
@@ -29,8 +29,8 @@
               <th>Information</th>
             </thead>
             <tr
-              v-for="(parameter, index) in operation.parameters"
-              :key="index">
+              v-for="parameter in operation.parameters"
+              :key="isParameterType(parameter) ? parameter.name : parameter.$ref">
               <OpenApiRequestParam
                 v-if="isParameterType(parameter)"
                 :parameter="parameter" />
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSchema.vue b/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
index 6e4c44d8..09f20a2d 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiSchema.vue
@@ -68,8 +68,8 @@
               class="px-2 py-2">
               <strong>All of:</strong>
               <div
-                v-for="(allOf, index) in property.allOf"
-                :key="index">
+                v-for="allOf in property.allOf"
+                :key="isSchemaObject(allOf) ? allOf.title : allOf.$ref">
                 <OpenApiSchema
                   v-show="!collapsible || (collapsible && showNested)"
                   :schema="allOf"
@@ -82,8 +82,8 @@
               class="px-2 py-2">
               <strong>One of:</strong>
               <div
-                v-for="(oneOf, index) in property.oneOf"
-                :key="index">
+                v-for="oneOf in property.oneOf"
+                :key="isSchemaObject(oneOf) ? oneOf.title : oneOf.$ref">
                 <OpenApiSchema
                   v-show="!collapsible || (collapsible && showNested)"
                   :schema="oneOf"
@@ -111,11 +111,11 @@
       <div v-if="schema.allOf">
         <em>All of:</em>
         <div
-          v-for="(item, index) in schema.allOf"
-          :key="index"
+          v-for="allOf in schema.allOf"
+          :key="isSchemaObject(allOf) ? allOf.title : allOf.$ref"
           class="ml-3">
           <OpenApiSchema
-            :schema="item"
+            :schema="allOf"
             :collapsible="false" />
         </div>
       </div>
@@ -123,11 +123,11 @@
       <div v-if="schema.oneOf">
         <em>One of:</em>
         <div
-          v-for="(item, index) in schema.oneOf"
-          :key="index"
+          v-for="oneOf in schema.oneOf"
+          :key="isSchemaObject(oneOf) ? oneOf.title : oneOf.$ref">
           class="ml-3">
           <OpenApiSchema
-            :schema="item"
+            :schema="oneOf"
             :collapsible="false" />
         </div>
       </div>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
index 7b6b7eec..4c1d248b 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
@@ -26,8 +26,8 @@
         v-if="schema.enum.length < 10"
         class="columns-2 list-disc">
         <li
-          v-for="(value, index) in schema.enum"
-          :key="index">
+          v-for="value in schema.enum"
+          :key="value">
           <code>{{ value }}</code>
         </li>
       </ul>
@@ -35,8 +35,8 @@
         <summary>View all</summary>
         <ul class="columns-2 list-disc">
           <li
-            v-for="(value, index) in schema.enum"
-            :key="index">
+            v-for="value in schema.enum"
+            :key="value">
             <code>{{ value }}</code>
           </li>
         </ul>
@@ -114,8 +114,8 @@
 
     <template v-if="schema.examples">
       <OpenApiExample
-        v-for="(example, index) in schema.examples"
-        :key="index"
+        v-for="example in schema.examples"
+        :key="example"
         :example="example" />
     </template>
   </header>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSecurityRequirements.vue b/src/.vuepress/theme/client/components/global/OpenApiSecurityRequirements.vue
index b23bd6b6..e2c9b995 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiSecurityRequirements.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiSecurityRequirements.vue
@@ -2,8 +2,8 @@
   <div v-if="resolvedSchemes?.length">
     <ul>
       <OpenApiSecurityScheme
-        v-for="(securityItem, index) in resolvedSchemes"
-        :key="index"
+        v-for="(securityItem, name) in resolvedSchemes"
+        :key="name"
         :scheme="securityItem" />
     </ul>
   </div>
@@ -20,13 +20,13 @@ const props = defineProps<{
 }>();
 
 const resolvedSchemes = computed(() => {
-  const resolved: OpenApiType.SecuritySchemeObject[] = [];
+  const resolved: Record<string, OpenApiType.SecuritySchemeObject> = {};
 
   for (const requirement of props.security) {
     const scheme = resolveRequirementToScheme(requirement);
 
     if (scheme) {
-      resolved.push(scheme);
+      resolved[Object.keys(requirement)[0]] = scheme;
     }
   }
 

From 0c44e9672bef46105a0bdc7ccc6e5665491851e3 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Fri, 19 Apr 2024 16:04:49 +0200
Subject: [PATCH 35/41] refactor(open-api): process feedback

---
 src/.vuepress/plugins/openApi.ts              | 10 ++++--
 .../client/components/global/OpenApi.vue      | 35 +------------------
 .../components/global/OpenApiExample.vue      |  7 +---
 .../components/global/OpenApiRequestParam.vue | 15 ++++----
 .../components/global/OpenApiResponses.vue    |  8 +++--
 .../components/global/OpenApiSchemaInfo.vue   | 29 +++++++++------
 .../components/global/OpenApiServers.vue      |  4 +--
 .../theme/client/utils/openApiHelpers.ts      |  9 +++++
 8 files changed, 51 insertions(+), 66 deletions(-)

diff --git a/src/.vuepress/plugins/openApi.ts b/src/.vuepress/plugins/openApi.ts
index c507b63a..27989940 100644
--- a/src/.vuepress/plugins/openApi.ts
+++ b/src/.vuepress/plugins/openApi.ts
@@ -28,7 +28,12 @@ export const openApiPlugin = (config: OpenApiPluginConfig): Plugin => ({
 function generateOpenApiPage(document: OpenApiType.Document) {
   return {
     path: `/api-reference/${kebabCase(document.info.title)}`,
-    content: `\
+    content: renderMarkdown(document),
+  };
+}
+
+function renderMarkdown(document: OpenApiType.Document): string {
+  return `\
 ---
 title: ${document.info.title}
 description: ${document.info.description}
@@ -48,8 +53,7 @@ ${document.servers?.length ? '## Servers' : ''}
 ${renderPaths(document, document.paths, 'Endpoints')}
 
 ${renderPaths(document, document.webhooks, 'Webhooks')}
-                  `,
-  };
+`;
 }
 
 function renderPaths(
diff --git a/src/.vuepress/theme/client/components/global/OpenApi.vue b/src/.vuepress/theme/client/components/global/OpenApi.vue
index 2ca27d0b..5e0ad966 100644
--- a/src/.vuepress/theme/client/components/global/OpenApi.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApi.vue
@@ -17,9 +17,9 @@
 <script setup lang="ts">
 import {computed} from 'vue';
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
-import {get} from 'lodash-es';
 import OpenApiPath from './OpenApiPath.vue';
 import OpenApiInfo from './OpenApiInfo.vue';
+import { resolveRefs } from '@mptheme/client/utils/openApiHelpers';
 
 const props = defineProps<{
   document: OpenApiType.Document;
@@ -31,37 +31,4 @@ const resolvedDocument = computed(() => resolveRefs(props.document));
 type RecursiveType = {
   [key: string]: unknown | RecursiveType | RecursiveType[];
 };
-
-function resolveRefs(document: OpenApiType.Document): OpenApiType.Document {
-  const resolvedDocument = {...document};
-
-  function resolveRefsRecursive(obj: RecursiveType) {
-    if (Array.isArray(obj)) {
-      for (const item of obj) {
-        resolveRefsRecursive(item);
-      }
-    } else if (typeof obj === 'object') {
-      for (const key in obj) {
-        if (key === '$ref') {
-          const lookup = obj[key] as string;
-          // Lookup is a string that defines the path to the referenced object like '#/components/schemas/Example'
-          const path = lookup.split('/').slice(1);
-          // Find the referenced object in the document using lodash's get function
-          const referencedObject = get(resolvedDocument, path);
-
-          // Remove the $ref: '...' key from the object and replace it with the referenced object itself
-          obj = Object.assign(obj, referencedObject);
-        } else if (typeof obj[key] === 'object' || Array.isArray(obj[key])) {
-          const guarded = obj[key] as RecursiveType;
-          // If the value is an object or an array, recursively call this function
-          resolveRefsRecursive(guarded);
-        }
-      }
-    }
-  }
-
-  resolveRefsRecursive(resolvedDocument);
-
-  return resolvedDocument;
-}
 </script>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiExample.vue b/src/.vuepress/theme/client/components/global/OpenApiExample.vue
index 0086ba2b..7a465074 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiExample.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiExample.vue
@@ -24,6 +24,7 @@ import {computed} from 'vue';
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
 import Markdown from '@mptheme/client/components/global/Markdown.vue';
 import CodeBlock from './CodeBlock.vue';
+import { formatExample } from '@mptheme/client/utils/openApiHelpers';
 
 const props = defineProps<{
   title?: string;
@@ -43,12 +44,6 @@ const formattedExample = computed(() => {
 // Check the formattedExample for linebreaks, if it has those, it's a multiline string
 const isMultilineString = computed(() => formattedExample.value?.includes('\n'));
 
-function formatExample(example: unknown): string {
-  const spacing = 2;
-
-  return JSON.stringify(example, null, spacing);
-}
-
 // Guard to check if example is an Example object
 const isExampleObject = (example: unknown): example is OpenApiType.ExampleObject => {
   return !!example && typeof example === 'object' && 'value' in example;
diff --git a/src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue b/src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue
index b517fe4a..503ba467 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiRequestParam.vue
@@ -10,9 +10,9 @@
       </span>
       <span
         v-for="flag in flags"
-        :key="flag"
-        >{{ flag }}</span
-      >
+        :key="flag">
+        {{ flag }}
+      </span>
     </template>
 
     <OpenApiSchema
@@ -20,10 +20,7 @@
       :schema="parameter.schema" />
 
     <Markdown
-      v-if="
-        parameter.description &&
-        !(parameter.schema && 'description' in parameter.schema && parameter.schema.description?.length)
-      "
+      v-if="parameter.description && !schemaHasDescription(parameter.schema)"
       class="text-gray-500 text-sm"
       :content="parameter.description" />
 
@@ -63,6 +60,10 @@ const props = defineProps<{
   parameter: OpenApiType.ParameterObject;
 }>();
 
+function schemaHasDescription(schema: OpenApiType.SchemaObject | undefined): boolean {
+  return !!(schema && 'description' in schema && schema.description?.length);
+}
+
 const flags = computed(() => {
   const arr: string[] = [];
 
diff --git a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
index dd5590e6..3178d47b 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
@@ -1,5 +1,5 @@
 <template>
-  <div v-if="Object.entries(responseObjects)?.length">
+  <div v-if="hasItems">
     <h4>Responses</h4>
     <ul class="m-0 p-0">
       <li
@@ -62,8 +62,10 @@ const props = defineProps<{
   responses: OpenApiType.ResponsesObject;
 }>();
 
-// Adds a computed to get only the OpenApiType.ResponseObject types from the responses prop.
-const responseObjects: ComputedRef<Record<string, OpenApiType.ResponseObject>> = computed(() => {
+const hasItems = computed<boolean>(() => Object.entries(props.responses).length > 0);
+
+  // Adds a computed to get only the OpenApiType.ResponseObject types from the responses prop.
+const responseObjects = computed<Record<string, OpenApiType.ResponseObject>>(() => {
   const objects: Record<string, OpenApiType.ResponseObject> = {};
   Object.entries(props.responses)
     .filter((response): response is [string, OpenApiType.ResponseObject] => isReponseObject(response))
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
index 4c1d248b..9ccf5cf0 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
@@ -66,41 +66,48 @@
     </div>
 
     <div v-if="schema.multipleOf !== undefined">
-      <strong class="inline-block text-sm">Multiple of:</strong> <code>{{ schema.multipleOf }}</code>
+      <strong class="inline-block text-sm">Multiple of:</strong>
+      <code>{{ schema.multipleOf }}</code>
     </div>
 
     <div v-if="schema.maximum !== undefined">
-      <strong class="inline-block text-sm">Max:</strong
-      ><code>{{ schema.exclusiveMaximum ? '<' : '<=' }} {{ schema.maximum }}</code>
+      <strong class="inline-block text-sm">Max:</strong>
+      <code>{{ schema.exclusiveMaximum ? '<' : '<=' }} {{ schema.maximum }}</code>
     </div>
 
     <div v-if="schema.minimum !== undefined">
-      <strong class="inline-block text-sm">Min:</strong
-      ><code>{{ schema.exclusiveMinimum ? '>' : '>=' }} {{ schema.minimum }}</code>
+      <strong class="inline-block text-sm">Min:</strong>
+      <code>{{ schema.exclusiveMinimum ? '>' : '>=' }} {{ schema.minimum }}</code>
     </div>
 
     <div v-if="schema.maxLength !== undefined">
-      <strong class="inline-block text-sm">Max length:</strong> <code>{{ schema.maxLength }}</code>
+      <strong class="inline-block text-sm">Max length:</strong>
+      <code>{{ schema.maxLength }}</code>
     </div>
 
     <div v-if="schema.minLength !== undefined">
-      <strong class="inline-block text-sm">Min length:</strong> <code>{{ schema.minLength }}</code>
+      <strong class="inline-block text-sm">Min length:</strong>
+      <code>{{ schema.minLength }}</code>
     </div>
 
     <div v-if="schema.maxItems !== undefined">
-      <strong class="inline-block text-sm">Max items:</strong> <code>{{ schema.maxItems }}</code>
+      <strong class="inline-block text-sm">Max items:</strong>
+      <code>{{ schema.maxItems }}</code>
     </div>
 
     <div v-if="schema.minItems !== undefined">
-      <strong class="inline-block text-sm">Min items:</strong> <code>{{ schema.minItems }}</code>
+      <strong class="inline-block text-sm">Min items:</strong>
+      <code>{{ schema.minItems }}</code>
     </div>
 
     <div v-if="schema.maxProperties !== undefined">
-      <strong class="inline-block text-sm">Max properties:</strong> <code>{{ schema.maxProperties }}</code>
+      <strong class="inline-block text-sm">Max properties:</strong>
+      <code>{{ schema.maxProperties }}</code>
     </div>
 
     <div v-if="schema.minProperties !== undefined">
-      <strong class="inline-block text-sm">Min properties:</strong> <code>{{ schema.minProperties }}</code>
+      <strong class="inline-block text-sm">Min properties:</strong>
+      <code>{{ schema.minProperties }}</code>
     </div>
 
     <div v-if="schema.additionalProperties !== undefined && typeof schema.additionalProperties === 'boolean'">
diff --git a/src/.vuepress/theme/client/components/global/OpenApiServers.vue b/src/.vuepress/theme/client/components/global/OpenApiServers.vue
index a383c95b..1058779c 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiServers.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiServers.vue
@@ -3,8 +3,8 @@
     v-if="servers?.length"
     class="open-api-servers">
     <li
-      v-for="(server, index) in servers"
-      :key="index">
+      v-for="server in servers"
+      :key="server.url">
       <code>{{ server.url }}</code>
       <Markdown
         v-if="server.description"
diff --git a/src/.vuepress/theme/client/utils/openApiHelpers.ts b/src/.vuepress/theme/client/utils/openApiHelpers.ts
index 7b564b79..c82f0901 100644
--- a/src/.vuepress/theme/client/utils/openApiHelpers.ts
+++ b/src/.vuepress/theme/client/utils/openApiHelpers.ts
@@ -5,6 +5,15 @@ type RecursiveType = {
   [key: string]: unknown | RecursiveType | RecursiveType[];
 };
 
+/**
+ * Formats an example object, array or primitive to a string
+ */
+export function formatExample(example: unknown): string {
+  const spacing = 2;
+
+  return JSON.stringify(example, null, spacing);
+}
+
 /**
  * Resolves all $ref keys in the document with their corresponding values
  */

From b94573f0e263aa4ffb7ee132723dab31ec1e832a Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Fri, 19 Apr 2024 16:23:49 +0200
Subject: [PATCH 36/41] refactor(open-api): clean up and improve html
 formatting

---
 .../components/global/OpenApiExample.vue      |  12 +-
 .../components/global/OpenApiOperation.vue    |  12 +-
 .../components/global/OpenApiSchemaInfo.vue   | 131 ++++++++++--------
 .../global/OpenApiSchemaInfoRestriction.vue   |  13 ++
 .../theme/client/components/global/index.ts   |   2 +
 5 files changed, 105 insertions(+), 65 deletions(-)
 create mode 100644 src/.vuepress/theme/client/components/global/OpenApiSchemaInfoRestriction.vue

diff --git a/src/.vuepress/theme/client/components/global/OpenApiExample.vue b/src/.vuepress/theme/client/components/global/OpenApiExample.vue
index 7a465074..bc06060f 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiExample.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiExample.vue
@@ -1,5 +1,5 @@
 <template>
-  <template v-if="example">
+  <div v-if="example">
     <strong class="inline-block text-sm">{{ title || 'Example' }}:</strong>&nbsp;
     <Markdown
       v-if="isExampleObject(example) && example.summary"
@@ -15,16 +15,20 @@
       v-if="formattedExample && isMultilineString"
       :code="formattedExample" />
 
-    <code v-else>{{ formattedExample }}</code>
-  </template>
+    <code
+      v-else
+      class="p-1">
+      {{ formattedExample }}
+    </code>
+  </div>
 </template>
 
 <script setup lang="ts">
 import {computed} from 'vue';
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
+import {formatExample} from '@mptheme/client/utils/openApiHelpers';
 import Markdown from '@mptheme/client/components/global/Markdown.vue';
 import CodeBlock from './CodeBlock.vue';
-import { formatExample } from '@mptheme/client/utils/openApiHelpers';
 
 const props = defineProps<{
   title?: string;
diff --git a/src/.vuepress/theme/client/components/global/OpenApiOperation.vue b/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
index 1619312d..a53ccccd 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiOperation.vue
@@ -1,11 +1,11 @@
 <template>
   <header class="bg-gray-100 dark:bg-gray-800 mb-4 mt-4 open-api-operation p-3">
     <strong>Endpoint:</strong>
-    <pre
+    <code
       class="dark:text-black inline-block leading-none m-0 ml-3 p-1 rounded-sm text-sm"
       :class="methodClass">
       {{ method.toUpperCase() }}
-    </pre>
+    </code>
     <pre class="dark:text-gray-100 inline m-0 ml-2 p-0 text-gray-700 text-sm">{{ endpoint }}</pre>
     <br />
 
@@ -34,13 +34,21 @@ const props = defineProps<{
 const methodClass = computed(() => {
   return {
     'bg-green-200': props.method === 'get',
+    'dark:bg-green-200': props.method === 'get',
     'bg-blue-200': props.method === 'post',
+    'dark:bg-blue-200': props.method === 'post',
     'bg-yellow-200': props.method === 'put',
+    'dark:bg-yellow-200': props.method === 'put',
     'bg-red-200': props.method === 'delete',
+    'dark:bg-red-200': props.method === 'delete',
     'bg-purple-200': props.method === 'patch',
+    'dark:bg-purple-200': props.method === 'patch',
     'bg-gray-200': props.method === 'options',
+    'dark:bg-gray-200': props.method === 'options',
     'bg-indigo-200': props.method === 'head',
+    'dark:bg-indigo-200': props.method === 'head',
     'bg-pink-200': props.method === 'trace',
+    'dark:bg-pink-200': props.method === 'trace',
   };
 });
 </script>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
index 9ccf5cf0..9e9fc4ab 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
@@ -43,16 +43,6 @@
       </details>
     </div>
 
-    <div v-if="schema && schema.default">
-      <strong class="inline-block text-sm">Default:</strong>&nbsp;
-      <code class="inline-block m-0 p-1 text-sm">{{ schema.default }}</code>
-    </div>
-
-    <div v-if="schema && schema.pattern">
-      <strong class="inline-block text-sm">Pattern:</strong>&nbsp;
-      <code class="inline-block m-0 p-1 text-sm">{{ schema.pattern }}</code>
-    </div>
-
     <div v-if="schema.externalDocs">
       <Markdown
         v-if="schema.externalDocs.description"
@@ -65,55 +55,78 @@
       >
     </div>
 
-    <div v-if="schema.multipleOf !== undefined">
-      <strong class="inline-block text-sm">Multiple of:</strong>
-      <code>{{ schema.multipleOf }}</code>
-    </div>
-
-    <div v-if="schema.maximum !== undefined">
-      <strong class="inline-block text-sm">Max:</strong>
-      <code>{{ schema.exclusiveMaximum ? '<' : '<=' }} {{ schema.maximum }}</code>
-    </div>
-
-    <div v-if="schema.minimum !== undefined">
-      <strong class="inline-block text-sm">Min:</strong>
-      <code>{{ schema.exclusiveMinimum ? '>' : '>=' }} {{ schema.minimum }}</code>
-    </div>
-
-    <div v-if="schema.maxLength !== undefined">
-      <strong class="inline-block text-sm">Max length:</strong>
-      <code>{{ schema.maxLength }}</code>
-    </div>
-
-    <div v-if="schema.minLength !== undefined">
-      <strong class="inline-block text-sm">Min length:</strong>
-      <code>{{ schema.minLength }}</code>
-    </div>
-
-    <div v-if="schema.maxItems !== undefined">
-      <strong class="inline-block text-sm">Max items:</strong>
-      <code>{{ schema.maxItems }}</code>
-    </div>
-
-    <div v-if="schema.minItems !== undefined">
-      <strong class="inline-block text-sm">Min items:</strong>
-      <code>{{ schema.minItems }}</code>
-    </div>
-
-    <div v-if="schema.maxProperties !== undefined">
-      <strong class="inline-block text-sm">Max properties:</strong>
-      <code>{{ schema.maxProperties }}</code>
-    </div>
-
-    <div v-if="schema.minProperties !== undefined">
-      <strong class="inline-block text-sm">Min properties:</strong>
-      <code>{{ schema.minProperties }}</code>
-    </div>
-
-    <div v-if="schema.additionalProperties !== undefined && typeof schema.additionalProperties === 'boolean'">
-      <strong class="inline-block text-sm">Additional properties:</strong>
-      <code>{{ !!schema.additionalProperties }}</code>
-    </div>
+    <OpenApiSchemaInfoRestriction
+      v-if="schema.default"
+      label="Default"
+      :value="schema.default"
+    />
+
+    <OpenApiSchemaInfoRestriction
+      v-if="schema.pattern"
+      label="Pattern"
+      :value="schema.pattern"
+    />
+
+
+    <OpenApiSchemaInfoRestriction
+      v-if="schema.multipleOf !== undefined"
+      label="Multiple of"
+      :value="schema.multipleOf"
+    />
+
+    <OpenApiSchemaInfoRestriction
+      v-if="schema.maximum !== undefined"
+      label="Max"
+      :value="schema.exclusiveMaximum ? '<' : '<=' + schema.maximum"
+    />
+
+    <OpenApiSchemaInfoRestriction
+      v-if="schema.minimum !== undefined"
+      label="Min"
+      :value="schema.exclusiveMinimum ? '>' : '>=' + schema.minimum"
+    />
+
+    <OpenApiSchemaInfoRestriction
+      v-if="schema.maxLength !== undefined"
+      label="Max length"
+      :value="schema.maxLength"
+    />
+
+    <OpenApiSchemaInfoRestriction
+      v-if="schema.minLength !== undefined"
+      label="Min length"
+      :value="schema.minLength"
+    />
+
+    <OpenApiSchemaInfoRestriction
+      v-if="schema.maxItems !== undefined"
+      label="Max items"
+      :value="schema.maxItems"
+    />
+
+    <OpenApiSchemaInfoRestriction
+      v-if="schema.minItems !== undefined"
+      label="Min items"
+      :value="schema.minItems"
+    />
+
+    <OpenApiSchemaInfoRestriction
+      v-if="schema.maxProperties !== undefined"
+      label="Max properties"
+      :value="schema.maxProperties"
+    />
+
+    <OpenApiSchemaInfoRestriction
+      v-if="schema.minProperties !== undefined"
+      label="Min properties"
+      :value="schema.minProperties"
+    />
+
+    <OpenApiSchemaInfoRestriction
+      v-if="schema.additionalProperties !== undefined && typeof schema.additionalProperties === 'boolean'"
+      label="Additional properties"
+      :value="!!schema.additionalProperties"
+    />
 
     <template v-if="schema.example">
       <OpenApiExample :example="schema.example" />
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfoRestriction.vue b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfoRestriction.vue
new file mode 100644
index 00000000..d651c7c3
--- /dev/null
+++ b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfoRestriction.vue
@@ -0,0 +1,13 @@
+<template>
+  <div class="whitespace-nowrap">
+    <strong class="inline-block text-sm">{{ label }}:</strong>
+    <code class="ml-2 p-1">{{ value }}</code>
+  </div>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+  label: string;
+  value: string;
+}>();
+</script>
diff --git a/src/.vuepress/theme/client/components/global/index.ts b/src/.vuepress/theme/client/components/global/index.ts
index 13b4a70c..c8e848a8 100644
--- a/src/.vuepress/theme/client/components/global/index.ts
+++ b/src/.vuepress/theme/client/components/global/index.ts
@@ -81,6 +81,8 @@ export {default as OpenApiSchema} from './OpenApiSchema.vue';
 
 export {default as OpenApiSchemaInfo} from './OpenApiSchemaInfo.vue';
 
+export {default as OpenApiSchemaInfoRestriction} from './OpenApiSchemaInfoRestriction.vue';
+
 export {default as OpenApiSecurityRequirements} from './OpenApiSecurityRequirements.vue';
 
 export {default as OpenApiSecurityScheme} from './OpenApiSecurityScheme.vue';

From ec35d95327f83bf2d0d319785b5277399f16f9df Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Tue, 23 Apr 2024 09:13:26 +0200
Subject: [PATCH 37/41] Update
 src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Remco Hörters <19972694+Cysword@users.noreply.github.com>
---
 .../theme/client/components/global/OpenApiSchemaInfo.vue        | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
index 9e9fc4ab..9d9fde01 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
@@ -66,8 +66,6 @@
       label="Pattern"
       :value="schema.pattern"
     />
-
-
     <OpenApiSchemaInfoRestriction
       v-if="schema.multipleOf !== undefined"
       label="Multiple of"

From 17ea752a4b181029fd417d45e8890fd2134d5ae5 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Tue, 23 Apr 2024 09:31:25 +0200
Subject: [PATCH 38/41] refactor(open-api): replace array index with value
 index

---
 src/.vuepress/config.ts                                |  2 +-
 .../theme/client/components/global/OpenApiExample.vue  |  6 +-----
 .../client/components/global/OpenApiResponses.vue      | 10 +++++-----
 src/.vuepress/theme/client/utils/openApiGuards.ts      |  5 +++++
 4 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/src/.vuepress/config.ts b/src/.vuepress/config.ts
index 2c88dd41..3e14f36b 100755
--- a/src/.vuepress/config.ts
+++ b/src/.vuepress/config.ts
@@ -27,7 +27,7 @@ export default defineUserConfig({
 
   plugins: [
     openApiPlugin({
-      yamlUrls: [],
+      yamlUrls: ['https://address.api.myparcel.nl/openapi.yaml'],
     }),
 
     parseTranslationsPlugin({
diff --git a/src/.vuepress/theme/client/components/global/OpenApiExample.vue b/src/.vuepress/theme/client/components/global/OpenApiExample.vue
index bc06060f..2e780b98 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiExample.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiExample.vue
@@ -27,6 +27,7 @@
 import {computed} from 'vue';
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
 import {formatExample} from '@mptheme/client/utils/openApiHelpers';
+import {isExampleObject} from '@mptheme/client/utils/openApiGuards';
 import Markdown from '@mptheme/client/components/global/Markdown.vue';
 import CodeBlock from './CodeBlock.vue';
 
@@ -47,9 +48,4 @@ const formattedExample = computed(() => {
 
 // Check the formattedExample for linebreaks, if it has those, it's a multiline string
 const isMultilineString = computed(() => formattedExample.value?.includes('\n'));
-
-// Guard to check if example is an Example object
-const isExampleObject = (example: unknown): example is OpenApiType.ExampleObject => {
-  return !!example && typeof example === 'object' && 'value' in example;
-};
 </script>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
index 3178d47b..8b612776 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiResponses.vue
@@ -38,8 +38,8 @@
             title="Example responses"
             tag="strong">
             <OpenApiExample
-              v-for="(example, index) in item.examples"
-              :key="index"
+              v-for="example in item.examples"
+              :key="isExampleObject(example) ? example.value : example.$ref"
               :example="example" />
           </DetailsExpand>
         </template>
@@ -49,9 +49,9 @@
 </template>
 
 <script setup lang="ts">
-import {computed, type ComputedRef} from 'vue';
+import {computed} from 'vue';
 import {type OpenAPIV3_1 as OpenApiType} from 'openapi-types';
-import {isReponseObject} from '@mptheme/client/utils/openApiGuards';
+import {isReponseObject, isExampleObject} from '@mptheme/client/utils/openApiGuards';
 import OpenApiSchema from './OpenApiSchema.vue';
 import OpenApiExample from './OpenApiExample.vue';
 import Markdown from './Markdown.vue';
@@ -64,7 +64,7 @@ const props = defineProps<{
 
 const hasItems = computed<boolean>(() => Object.entries(props.responses).length > 0);
 
-  // Adds a computed to get only the OpenApiType.ResponseObject types from the responses prop.
+// Adds a computed to get only the OpenApiType.ResponseObject types from the responses prop.
 const responseObjects = computed<Record<string, OpenApiType.ResponseObject>>(() => {
   const objects: Record<string, OpenApiType.ResponseObject> = {};
   Object.entries(props.responses)
diff --git a/src/.vuepress/theme/client/utils/openApiGuards.ts b/src/.vuepress/theme/client/utils/openApiGuards.ts
index 16f0dd87..ca137a93 100644
--- a/src/.vuepress/theme/client/utils/openApiGuards.ts
+++ b/src/.vuepress/theme/client/utils/openApiGuards.ts
@@ -20,3 +20,8 @@ export const isArraySchemaObject = (schema: object): schema is OpenApiType.Array
 export const isReponseObject = (response: object): response is OpenApiType.ResponseObject => {
   return typeof response === 'object';
 };
+
+// Guard to check if example is an Example object
+export const isExampleObject = (example: unknown): example is OpenApiType.ExampleObject => {
+  return !!example && typeof example === 'object' && 'value' in example;
+};

From 9d9d8b19d53b2178de81932a95b7de0cd7629685 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Tue, 23 Apr 2024 09:35:47 +0200
Subject: [PATCH 39/41] fix(open-api): fix security schemes never rendering

---
 .../client/components/global/OpenApiSchemaInfoRestriction.vue   | 2 +-
 .../client/components/global/OpenApiSecurityRequirements.vue    | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfoRestriction.vue b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfoRestriction.vue
index d651c7c3..1c648407 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfoRestriction.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfoRestriction.vue
@@ -8,6 +8,6 @@
 <script setup lang="ts">
 defineProps<{
   label: string;
-  value: string;
+  value: string | number;
 }>();
 </script>
diff --git a/src/.vuepress/theme/client/components/global/OpenApiSecurityRequirements.vue b/src/.vuepress/theme/client/components/global/OpenApiSecurityRequirements.vue
index e2c9b995..d605387a 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiSecurityRequirements.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiSecurityRequirements.vue
@@ -1,5 +1,5 @@
 <template>
-  <div v-if="resolvedSchemes?.length">
+  <div v-if="Object.keys(resolvedSchemes)?.length">
     <ul>
       <OpenApiSecurityScheme
         v-for="(securityItem, name) in resolvedSchemes"

From 02680c6c2d39940eef8ea9d3b9bc4df9b41c7263 Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Tue, 23 Apr 2024 12:53:54 +0200
Subject: [PATCH 40/41] docs(open-api): do not publish  address API for now

---
 src/.vuepress/config.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/.vuepress/config.ts b/src/.vuepress/config.ts
index 3e14f36b..2c88dd41 100755
--- a/src/.vuepress/config.ts
+++ b/src/.vuepress/config.ts
@@ -27,7 +27,7 @@ export default defineUserConfig({
 
   plugins: [
     openApiPlugin({
-      yamlUrls: ['https://address.api.myparcel.nl/openapi.yaml'],
+      yamlUrls: [],
     }),
 
     parseTranslationsPlugin({

From ce11a5ed86f70e0cb598dada0b6b25c44498b2ee Mon Sep 17 00:00:00 2001
From: Freek van Rijt <freek.vanrijt@myparcel.nl>
Date: Wed, 24 Apr 2024 09:34:28 +0200
Subject: [PATCH 41/41] refactor(open-api): remove redundant checks for schema
 prop

INT-407
---
 .../theme/client/components/global/OpenApiSchemaInfo.vue  | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
index 9d9fde01..62225667 100644
--- a/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
+++ b/src/.vuepress/theme/client/components/global/OpenApiSchemaInfo.vue
@@ -1,7 +1,7 @@
 <template>
   <header>
     <strong v-if="title">{{ title }}</strong>
-    <strong v-else-if="schema && schema.title">{{ schema.title }}</strong>
+    <strong v-else-if="schema.title">{{ schema.title }}</strong>
     <span
       v-if="isRequired"
       title="Required"
@@ -9,18 +9,18 @@
       >*</span
     >
     <pre
-      v-if="schema && schema.type"
+      v-if="schema.type"
       class="m-0 p-0 text-sm whitespace-nowrap">
           {{ schema.type }}
           <template v-if="schema.format">({{ schema.format }})</template>
       </pre>
 
     <Markdown
-      v-if="schema && schema.description"
+      v-if="schema.description"
       :content="schema.description"
       class="m-0 p-0 text-gray-500 text-sm" />
 
-    <div v-if="schema && schema.enum?.length">
+    <div v-if="schema.enum?.length">
       <strong class="text-sm">Possible values:</strong>
       <ul
         v-if="schema.enum.length < 10"