From 758d0dc781ca099daf9628cca4a9c39676df5078 Mon Sep 17 00:00:00 2001
From: Jilles van Gurp <jillesvangurp@users.noreply.github.com>
Date: Wed, 1 Apr 2026 20:43:25 +0200
Subject: [PATCH] docs: add Redoc API reference for hub spec

---
 content/open-location-hub/_index.md           |  4 +-
 .../open-location-hub/docs/api-reference.md   |  8 +++
 layouts/_default/redoc.html                   | 53 +++++++++++++++++++
 3 files changed, 64 insertions(+), 1 deletion(-)
 create mode 100644 content/open-location-hub/docs/api-reference.md
 create mode 100644 layouts/_default/redoc.html

diff --git a/content/open-location-hub/_index.md b/content/open-location-hub/_index.md
index 50ccd64..8f1e9f3 100644
--- a/content/open-location-hub/_index.md
+++ b/content/open-location-hub/_index.md
@@ -13,7 +13,7 @@ It is the integration-layer counterpart to Open Location Stack's mapping work: o
 
 The current repository is still evolving quickly, but the intended direction is already clear: a production-grade, open source hub that teams can run, extend, adapt, and integrate without being locked into vendor-specific middleware.
 
-The software documentation for the current implementation is published at [Open Location Hub Docs](/open-location-hub/docs/). That section is generated from the repository's `docs/` directory and is intended to stay aligned with the code as the project evolves.
+The software documentation for the current implementation is published at [Open Location Hub Docs](/open-location-hub/docs/). The REST contract is available as an interactive [API Reference](/open-location-hub/docs/api-reference/).
 
 ## Business value
 
@@ -98,6 +98,8 @@ If you care about interoperable RTLS infrastructure, now is the right time to ge
 
 [Browse the generated docs](/open-location-hub/docs/)
 
+[Open the API reference](/open-location-hub/docs/api-reference/)
+
 [Learn about Floor Plan Editor](/floor-plan-editor/)
 
 [View the repository on GitHub](https://github.com/Open-Location-Stack/open-location-hub)
diff --git a/content/open-location-hub/docs/api-reference.md b/content/open-location-hub/docs/api-reference.md
new file mode 100644
index 0000000..1e83ae0
--- /dev/null
+++ b/content/open-location-hub/docs/api-reference.md
@@ -0,0 +1,8 @@
+---
+title: "API Reference"
+description: "Interactive OpenAPI reference for the Open Location Hub REST contract."
+draft: false
+layout: "redoc"
+spec_url: "https://raw.githubusercontent.com/Open-Location-Stack/open-location-hub/main/specifications/openapi/omlox-hub.v0.yaml"
+github_url: "https://github.com/Open-Location-Stack/open-location-hub/blob/main/specifications/openapi/omlox-hub.v0.yaml"
+---
diff --git a/layouts/_default/redoc.html b/layouts/_default/redoc.html
new file mode 100644
index 0000000..915759a
--- /dev/null
+++ b/layouts/_default/redoc.html
@@ -0,0 +1,53 @@
+{{ define "main" }}
+  <article class="mx-auto max-w-7xl px-4 py-12 sm:px-6 md:px-8 md:py-20">
+    <header class="max-w-3xl">
+      <h1 class="text-3xl font-semibold tracking-tight sm:text-4xl">{{ .Title }}</h1>
+      {{ with .Description }}
+        <p class="mt-4 text-base leading-relaxed text-muted sm:text-lg">{{ . }}</p>
+      {{ end }}
+      <div class="mt-4 flex flex-wrap items-center gap-3">
+        {{ with .Params.github_url }}
+          <a href="{{ . }}" class="inline-flex items-center gap-2 rounded-full border border-line px-4 py-2 text-sm font-medium text-muted transition hover:border-ink hover:text-ink" aria-label="View {{ $.Title }} source on GitHub">
+            {{ partial "github-icon.html" (dict "class" "h-4 w-4") }}
+            <span>OpenAPI YAML</span>
+          </a>
+        {{ end }}
+      </div>
+    </header>
+
+    <section class="mt-10 overflow-hidden rounded-2xl border border-line bg-white shadow-sm">
+      <div id="redoc-container" class="min-h-[80vh]"></div>
+    </section>
+  </article>
+
+  <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
+  <script>
+    const redocSpecUrl = {{ .Params.spec_url | jsonify }};
+    Redoc.init(
+      redocSpecUrl,
+      {
+        hideHostname: true,
+        expandResponses: "200,201",
+        pathInMiddlePanel: true,
+        nativeScrollbars: true,
+        theme: {
+          colors: {
+            primary: {
+              main: "#111111"
+            }
+          },
+          typography: {
+            fontFamily: "ui-sans-serif, system-ui, sans-serif",
+            headings: {
+              fontFamily: "ui-sans-serif, system-ui, sans-serif"
+            },
+            code: {
+              fontFamily: "ui-monospace, SFMono-Regular, monospace"
+            }
+          }
+        }
+      },
+      document.getElementById("redoc-container")
+    );
+  </script>
+{{ end }}