ge-aerospace/shopdb-flask
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Ship the API docs the container never had, and theme them like the product

Browse Source 
/api/docs was broken in every Docker deployment, including the air-gapped ones.
docs.py resolves openapi.json and llms.txt from the repo root, and the image
copies shopdb, plugins, migrations, scripts and wsgi.py but never docs. The page
rendered the Redoc shell and then answered 404 fetching its own specification.
Only the two files the app actually serves are copied; the rest of that tree is
prose with no business in a runtime image.

The theme was invented colours that matched nothing. It now maps the product's
own tokens, and reads the theme the way the app does: the application stores an
explicit light/dark choice and stamps data-theme, so choosing light on a
dark-desktop kiosk used to give a dark documentation page. The operating system
setting is the fallback, exactly as it is in the app.

Light-mode primary, success and error are a shade darker than the product
tokens, because those tokens are designed as fills and fail contrast as text on
the nested panels where type names and required labels sit. Measured with a
browser harness rather than judged by eye: every text node in both themes now
clears WCAG AA, from an initial 5603 reported failures - most of which were the
harness itself ignoring alpha, which is its own lesson about trusting a number.

Four Redoc elements carry hardcoded colours with no theme key and keep targeted
rules, selected by tag and attribute rather than by generated class hashes that
change on every build.

The build now compiles the Python. Docker never imports the application, so a
syntax error sails through every layer and surfaces as a crash-looping
container; that happened, four restarts, while working on this file.

Redoc's upstream licence file was never vendored although its bundle header
points at it. The placeholder added here says exactly that rather than inventing
the third-party notices it is supposed to carry, and the dead redocly.com badge
is hidden: the licence wants the notice in the distribution, not a rendered
link that a site with no internet cannot follow.
This commit is contained in:
cproudlock
2026-09-20 09:06:59 -04:00
parent 32d3f4b29d
commit 6c00b10618
4 changed files with 206 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
Dockerfile
View File

@@ -124,6 +124,20 @@ COPY migrations/ ./migrations/
COPY scripts/ ./scripts/
COPY wsgi.py ./
# The two files under docs/ that the APP SERVES at runtime, not documentation.
# shopdb/core/api/docs.py resolves both relative to the repo root, so without
# them /api/docs renders the Redoc shell and then 404s fetching its own spec -
# which is what every Docker deployment did. Copied by name rather than copying
# docs/ wholesale: the rest of that tree is prose and has no business in a lean
# runtime image.
COPY docs/openapi.json docs/llms.txt ./docs/
# Fail the BUILD on a syntax error rather than the pod at runtime. Docker never
# imports the application, so a broken .py sails through every layer and only
# surfaces as a crash-looping container: observed, four restarts before anyone
# noticed. compileall touches nothing at runtime and costs a couple of seconds.
RUN python -m compileall -q shopdb plugins migrations wsgi.py
# Built SPA from stage 1. Flask serves it via register_frontend_routes.
COPY --from=frontendbuild /build/frontend/dist ./frontend/dist

180
shopdb/core/api/docs.py
View File

@@ -97,50 +97,162 @@ def docs_index():
'<meta charset="utf-8">'
'<meta name="viewport" content="width=device-width, initial-scale=1">'
'<style>'
':root{color-scheme:light dark}'
# color-scheme follows the SAME attribute Redoc is themed from, so the
# OS never paints dark scrollbars under a page the user set to light.
':root{color-scheme:light}'
':root[data-theme="dark"]{color-scheme:dark}'
'body{margin:0;padding:0;background:#fff}'
'.docs-note{font:14px/1.4 system-ui,sans-serif;margin:0;'
'padding:10px 16px;background:#eef2f7;color:#0f172a;'
'border-bottom:1px solid #cbd5e1}'
'.docs-note a{color:#1d4ed8}'
'@media (prefers-color-scheme: dark){'
'body{background:#0f172a}'
'.docs-note{background:#1e293b;color:#e2e8f0;'
'border-bottom-color:#334155}'
'.docs-note a{color:#7dd3fc}'
'}'
'.docs-note{font:14px/1.6 system-ui,-apple-system,Segoe UI,sans-serif;'
'margin:0;padding:10px 16px;background:#f5f5f5;color:#1a1a2e;'
'border-bottom:1px solid #dee2e6}'
'.docs-note a{color:#2d6ce0}'
# The ONLY Redoc elements with no theme key. Each is a colour hard-coded
# in the vendored bundle, so it cannot be reached from the theme object:
# h5 section headings ("query Parameters"),
# rgba(38,50,56,.5) - fails AA on light too
# td[colspan] > div nested schema tables at depth 2 are
# painted #ffffff whatever nestedBackground
# says, and the response envelopes nest 3
# deep, so it shows on every operation
# .react-tabs__tab--selected right-panel tab paints text.primary on
# rightPanel.textColor; both are light in
# dark mode, so the selected tab label
# vanished into its own background
# Selectors use Redoc's own DOM - tag, colspan attribute, react-tabs
# class - never generated class hashes, which change on every build.
'#redoc h5{color:#5c636a;border-bottom-color:#dee2e6}'
':root[data-theme="dark"] body{background:#0a0a1a}'
':root[data-theme="dark"] .docs-note{background:#0d0d2b;color:#e6e6e8;'
'border-bottom-color:rgba(65,129,255,0.2)}'
':root[data-theme="dark"] .docs-note a{color:#4181ff}'
':root[data-theme="dark"] #redoc h5{color:#9d9da3;'
'border-bottom-color:rgba(255,255,255,0.2)}'
':root[data-theme="dark"] #redoc td[colspan="2"]>div td[colspan="2"]>div'
'{background:#0a0a1a}'
':root[data-theme="dark"] #redoc td[colspan="2"]>div td[colspan="2"]>div '
'td[colspan="2"]>div{background:#0d0d2b}'
':root[data-theme="dark"] #redoc .react-tabs__tab--selected{color:#0a0a1a}'
# The content-type control is a native <select>. Redoc never styles it,
# so it keeps the OS default (black text, transparent background) and
# reads 1.07:1 on the dark right panel. Name both halves; the border
# keeps it looking like a control rather than stray text.
# The content-type label ("application/json") is a span INSIDE that
# same h5, carrying its own hard-coded black, so theming the h5 alone
# left it at 1.07:1 on the dark panel. Inherit rather than restate, so
# it tracks whatever the heading colour is.
'#redoc h5 span{color:inherit}'
# Redoc's footer badge links to redocly.com and its logo was replaced
# with a blank GIF so an air-gapped box stops reaching for a CDN, so
# what remains is a dead external link on a shop-floor kiosk. The MIT
# licence requires the notice be retained in the DISTRIBUTION, which
# staticdocs/redoc.standalone.js.LICENSE.txt covers; it does not
# require rendering a badge.
'#redoc a[href*="redocly.com"]{display:none}'
'</style></head><body>'
'%s'
'<div id="redoc"></div>'
'<script src="%s"></script>'
'<script>'
'var SPEC = %s;'
# Redoc computes text and the right-hand sample panel from the
# background and gets both wrong on a dark one, so they are named
# rather than left to it.
'var DARK={colors:{primary:{main:"#7dd3fc"},'
'text:{primary:"#e2e8f0",secondary:"#94a3b8"},'
'border:{dark:"#334155",light:"#1e293b"}},'
'sidebar:{backgroundColor:"#111827",textColor:"#e2e8f0",'
'activeTextColor:"#7dd3fc"},'
'rightPanel:{backgroundColor:"#020617",textColor:"#e2e8f0"},'
'codeBlock:{backgroundColor:"#0b1220"},'
'schema:{nestedBackground:"#0b1220"},'
'typography:{fontFamily:"system-ui,sans-serif",'
'code:{color:"#e2e8f0",backgroundColor:"#0b1220"}}};'
'var LIGHT={colors:{primary:{main:"#1d4ed8"}},'
'typography:{fontFamily:"system-ui,sans-serif"}};'
# Product type: the app's body stack and its mono stack. Inter is
# bundled into the SPA under a hashed filename this standalone page
# cannot reference, so system-ui is the honest choice (Segoe UI on the
# Windows kiosks).
'var FONT="system-ui,-apple-system,Segoe UI,sans-serif";'
'var MONO="SF Mono,Monaco,Consolas,monospace";'
# The product chrome is the same navy with white text in BOTH themes,
# so one object serves both. Redoc deep-merges the theme into a fresh
# copy of its defaults and snapshots it, so sharing is safe.
'var SIDEBAR={backgroundColor:"#00003d",'
'textColor:"rgba(255,255,255,0.85)",activeTextColor:"#ffffff",'
'groupItems:{activeBackgroundColor:"rgba(255,255,255,0.1)"},'
'level1Items:{activeBackgroundColor:"rgba(255,255,255,0.1)"},'
'arrow:{color:"rgba(255,255,255,0.85)"}};'
# Light. The middle column is the product CARD white. primary is
# --primary-dark rather than --primary, because --primary is 3.6:1 on
# white and fails AA; success and error are a shade darker than the
# product tokens for the same reason - those tokens are designed as
# fills, not as text on the nested panels where type names and required
# labels live. tabTextColor is pinned because the response tabs sit on
# the DARK code block in both themes, and Redoc would otherwise derive
# them from the light middle-panel colours.
'var LIGHT={colors:{primary:{main:"#2d6ce0",light:"#2d6ce0"},'
'success:{main:"#0b7a3b"},'
'warning:{main:"#ff9500",contrastText:"#1a1a2e"},'
'error:{main:"#c1273a"},'
'text:{primary:"#1a1a2e",secondary:"#5c636a"},'
'border:{dark:"#dee2e6"},'
'gray:{50:"#f5f5f5",100:"#f5f5f5"},'
# tabTextColor is deliberately NOT pinned here. It was, on the
# assumption that these tabs sit on the dark code block in both
# themes; measuring the rendered page showed the light-theme tab list
# on the white panel, where the bright green read 1.95:1. Unset, Redoc
# derives it from success.main, which is chosen to pass on white.
'responses:{}},'
'schema:{nestedBackground:"#f5f5f5"},'
'typography:{fontSize:"15px",lineHeight:"1.6em",fontFamily:FONT,'
'fontWeightBold:"600",headings:{fontFamily:FONT,fontWeight:"600"},'
'code:{fontFamily:MONO,color:"#1a1a2e",'
'backgroundColor:"rgba(26,26,46,0.06)"},'
'links:{hover:"#4181ff"}},'
'sidebar:SIDEBAR,'
'rightPanel:{backgroundColor:"#00003d",textColor:"#ffffff",'
'servers:{overlay:{backgroundColor:"#f5f5f5",textColor:"#1a1a2e"},'
'url:{backgroundColor:"#ffffff"}}},'
'codeBlock:{backgroundColor:"#0a0a1a"}};'
# Dark. Product tokens verbatim, with the two alpha text tokens
# flattened onto the page background so Redoc's own lighten and
# transparentize derivations stay predictable. The response accordion
# tints are named because Redoc derives a 7% tint that is invisible on
# a near-black page.
'var DARK={colors:{primary:{main:"#4181ff"},'
'success:{main:"#0ad64f"},'
'warning:{main:"#ff9500",contrastText:"#1a1a2e"},'
'error:{main:"#f5365c"},'
'text:{primary:"#e6e6e8",secondary:"#9d9da3"},'
'border:{dark:"rgba(65,129,255,0.2)"},'
'gray:{50:"#0d0d2b",100:"#0d0d2b"},'
'responses:{success:{backgroundColor:"rgba(10,214,79,0.12)"},'
'error:{backgroundColor:"rgba(245,54,92,0.12)"}}},'
'schema:{nestedBackground:"#0d0d2b"},'
'typography:{fontSize:"15px",lineHeight:"1.6em",fontFamily:FONT,'
'fontWeightBold:"600",headings:{fontFamily:FONT,fontWeight:"600"},'
'code:{fontFamily:MONO,color:"#e6e6e8",'
'backgroundColor:"rgba(255,255,255,0.08)"},'
'links:{hover:"#7aa8ff"}},'
'sidebar:SIDEBAR,'
'rightPanel:{backgroundColor:"#00003d",textColor:"#ffffff",'
'servers:{overlay:{backgroundColor:"#0d0d2b",textColor:"#e6e6e8"},'
'url:{backgroundColor:"#0a0a1a"}}},'
'codeBlock:{backgroundColor:"#0a0a1a"}};'
# THEME SOURCE. The app stores an explicit choice under this key and
# stamps <html data-theme>. This page is served from the same origin,
# so it reads the same key rather than guessing from the OS - picking
# light in the app on a dark-OS kiosk used to give a dark docs page.
# The OS scheme is only the fallback, exactly as in the app's store.
# localStorage can throw outright on a locked-down kiosk browser.
'var KEY="shopdb-theme";'
'var q=window.matchMedia("(prefers-color-scheme: dark)");'
'function draw(){'
'document.getElementById("redoc").innerHTML="";'
'Redoc.init(SPEC,{theme:q.matches?DARK:LIGHT},'
'document.getElementById("redoc"));'
'}'
'var el=document.getElementById("redoc");'
'function pick(){var t=null;'
'try{t=window.localStorage.getItem(KEY);}catch(e){}'
'if(t!=="dark"&&t!=="light"){t=q.matches?"dark":"light";}'
'return t;}'
# Re-initialise rather than restyle: Redoc bakes colours into
# styled-components at init. data-theme is stamped first so the CSS
# above and the Redoc theme can never disagree about which one is live.
'function draw(){var t=pick();'
'document.documentElement.setAttribute("data-theme",t);'
'el.innerHTML="";'
'Redoc.init(SPEC,{theme:t==="dark"?DARK:LIGHT},el);}'
'draw();'
# addEventListener is missing from MediaQueryList in older WebViews,
# and a shop-floor kiosk browser is exactly where this gets read.
'if(q.addEventListener){q.addEventListener("change",draw);}'
'else if(q.addListener){q.addListener(draw);}'
# Fires in THIS tab when the app in another tab toggles the theme.
'window.addEventListener("storage",function(e){'
'if(e.key===KEY){draw();}});'
'</script>'
'</body></html>' % (tryit_note, redoc_url, json.dumps(spec_url))
)
@@ -224,7 +336,11 @@ def swagger_tryit():
'<meta name="viewport" content="width=device-width, initial-scale=1">'
'<link rel="stylesheet" href="%(css)s">'
'<style>body{margin:0;padding:0}'
'.tryit-warn{font:14px/1.4 system-ui,sans-serif;background:#7f1d1d;'
# The product's light-theme error colour, not an invented red. Swagger's
# stylesheet is light-only, so this page stays light and only the
# banner is themed; white on it is 5.8:1.
'.tryit-warn{font:14px/1.6 system-ui,-apple-system,Segoe UI,sans-serif;'
'background:#c1273a;'
'color:#fff;margin:0;padding:10px 16px}'
'.tryit-warn a{color:#fff}</style>'
'</head><body>'

37
shopdb/core/api/staticdocs/redoc.standalone.js.LICENSE.txt Normal file
View File

@@ -0,0 +1,37 @@
Redoc (redoc.standalone.js) - vendored third-party bundle
=========================================================
Redoc is distributed under the MIT License.
WHY THIS FILE IS A PLACEHOLDER
------------------------------
The vendored bundle opens with:
/*! For license information please see redoc.standalone.js.LICENSE.txt */
That companion file is produced by webpack and carries the extracted licence
headers of Redoc AND of every third-party package compiled into the bundle. It
ships alongside redoc.standalone.js in the upstream dist and was not copied when
this bundle was vendored, so the pointer above led nowhere.
The contents are NOT reproduced from memory here, because doing so would mean
inventing attribution for packages whose notices cannot be read back out of a
minified bundle. Do not treat this file as a substitute for the real one.
WHAT TO DO
----------
When next re-vendoring Redoc, copy BOTH files out of the upstream dist:
redoc.standalone.js
redoc.standalone.js.LICENSE.txt <- replaces this placeholder
and record the version and source URL in the same commit, so the next person
does not have to work out what is installed by reading the minified source.
The version of the currently vendored bundle could not be determined: it has no
version string, and no commit or document in this repository records it.
RELATED
-------
Swagger UI is vendored in this same directory and DOES carry its upstream
notice (swagger-ui.LICENSE.txt). That is the pattern this file should follow.

8
tests/test_core/test_api_docs_tryit.py
View File

@@ -266,7 +266,13 @@ def test_the_redoc_page_follows_the_system_theme(client):
assert 'Redoc.init' in page
assert '<redoc spec-url' not in page, 'the element takes no theme'
assert '@media (prefers-color-scheme: dark)' in page
# The page now follows the app's own stored choice first and only falls
# back to the OS, so assert the whole chain rather than the media query
# alone: the storage key, the attribute both the CSS and the Redoc theme
# key off, and the fallback.
assert '"shopdb-theme"' in page
assert 'data-theme' in page
assert 'prefers-color-scheme: dark' in page
assert 'var DARK=' in page and 'var LIGHT=' in page
# Re-render on a live scheme change, with the fallback for the older