Skip to content

feat(qui-docs): add OpenAPI support - #422

Open
Olaf (olaf-k) wants to merge 33 commits into
qualcomm:mainfrom
olaf-k:olaf/feat/openapi-docs
Open

Olaf (olaf-k) wants to merge 33 commits into
qualcomm:mainfrom
olaf-k:olaf/feat/openapi-docs

Conversation

@olaf-k

@olaf-k Olaf (olaf-k) commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

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 openApiExpanded prop 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

  • JSON only for now, YAML support planned in v2. specs are upgraded to 3.2 on load, so there's only one format to deal with.
  • local $refs are inlined, except in examples as per OAI specs (GH doesn't respect that). refs to other files are left as they are.
  • remote specs are fetched at build time and in dev. editing a local spec in dev reloads its pages.
  • readOnly fields are dropped from request bodies and writeOnly fields 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 fix commits

  • the React Select always rendered an empty label which pushed the control 2px down, and leaked item="[object Object]" onto every option.
  • links inside MDX paragraphs and list items changed to display: inline to allow them to wrap.
  • breadcrumbs: a parent path without a page entry crashed the breadcrumbs.
  • alerts: the shared remarkAlerts plugin crashed on an alert marker followed directly by a list.
  • (perf rather than fix) the mobile sidebar drawer remounted a hidden copy of the whole sidebar on every navigation, even on desktop.
  • qui-docs' knowledge exclude patterns still used folder names from before the routing migration, so they matched nothing.

planned for next versions

  • "Try it" requests. simple one (v2) and a full request form (v3).
  • YAML spec support.
  • nested tag groups (Tag.parent, x-tagGroups).
  • auth headers in samples.
  • redesigned site-wide layout (separate PR).

@R-Bower Ryan Bower (R-Bower) left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

First review. Haven't covered everything yet but I'll submit this to give you some stuff to work on

Comment on lines +18 to +20
* 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.
*/

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

some specs may be very large. Did you test the limits of this? I am wondering what the size constraint is.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's see if we can adopt the JSON Viewer here

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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>
@olaf-k
Olaf (olaf-k) marked this pull request as ready for review November 20, 2026 14:58
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>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants