Repository navigation
feat(qui-docs): add OpenAPI support - #422
Olaf (olaf-k) wants to merge 33 commits into
Conversation
f53caad to
b2e0c5a
Compare
Ryan Bower (R-Bower)
left a comment
There was a problem hiding this comment.
First review. Haven't covered everything yet but I'll submit this to give you some stuff to work on
| * Each operation is its own lazily imported module, so a page only loads its | ||
| * own data: a large spec embedded in a single module can exhaust Vite's memory. | ||
| */ |
There was a problem hiding this comment.
some specs may be very large. Did you test the limits of this? I am wondering what the size constraint is.
There was a problem hiding this comment.
the first attempt used only one virtual module for every operation of every spec. this made Vite quickly run out of memory when loading GH's. the "one operation per module" split precisely works around that.
re: numbers, GH's specs weighs ~14MB as a JSON file and expands to ~25MB once all the $ref are inlined. for comparison, the other ones (Pet Store/Scalar/QDC) only add 200kB combined.
| @@ -0,0 +1,94 @@ | |||
| // Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries. | |||
There was a problem hiding this comment.
http://re-qdswc-runner:8080/guide/github/actions/get-actions-cache-retention-limit-for-enterprise
vs.
https://docs.github.com/en/rest/actions/artifacts?apiVersion=2026-03-10
Note the sidebars. Their grouping strategy is much cleaner. Ours is a bit overwhelming because it shows every route all at once. What if we grouped by endpoint? This would help organize large APIs like GitHub's.
Check the Teams chat w/ Stephen
| @@ -0,0 +1,140 @@ | |||
| // Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries. | |||
There was a problem hiding this comment.
let's see if we can adopt the JSON Viewer here
There was a problem hiding this comment.
this component is the one that displays the schema, so the viewer is not useful for this part. it might be in code-samples-panel.tsx which displays the response example though. I added it to my TODO.
b2e0c5a to
091f749
Compare
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
46298d8 to
999d863
Compare
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
…utes Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
…hey don't apply Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
…ptions Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
999d863 to
b689f67
Compare
overview
this PR adds support for rendering an OpenAPI spec. authors can set
openApi: ./spec.json(path or URL) in an MDX page's frontmatter. that page becomes the API's intro page, and every operation in the spec gets its own generated page under it.each operation page shows the method and path, the MD description, parameters, request body and responses. a side panel holds request samples (for now: cURL, JavaScript, Python), plus example responses per status code.
API pages handle their own sidenav. a switcher at the top of it allows navigation between global nav and OAI specs. the sidenav lists operations in one collapsible section per tag. the frontmatter
openApiExpandedprop controls how every section should appear by default (the current operation's section is always open).operations are indexed for site search and included in the AI knowledge export. semantic and legacy search are supported, LMK if the latter is unnecessary.
the docs page,
openapi.mdx, covers setup, the frontmatter fields and the limits.specs
$refs are inlined, except in examples as per OAI specs (GH doesn't respect that). refs to other files are left as they are.readOnlyfields are dropped from request bodies andwriteOnlyfields from responses.tested on Pet Store, Scalar's Planets API, the QDC API, and GitHub's REST spec as a stress case (~14MB, ~1300 operations).
additional standalone
fixcommitsSelectalways rendered an empty label which pushed the control 2px down, and leakeditem="[object Object]"onto every option.display: inlineto allow them to wrap.remarkAlertsplugin crashed on an alert marker followed directly by a list.excludepatterns still used folder names from before the routing migration, so they matched nothing.planned for next versions
Tag.parent,x-tagGroups).