Unified Sumo API docs with API references page (Redocusaurus)

[JV0812]

Purpose of this pull request

This pull request is to avoid opening a new tab to open the API references page, instead treat it as our usual docusaurus page. I have used Redocusaurus plugin to work on it. Also, made sure the font size, style, the code block, and code properties are inline with our usual doc styles.

To add on, the only drawback we can face is the delayed time (2-3 seconds more) to load this page (pulled from an YAML file) as it contains about 36k lines to read.

Select the type of change

• Minor Changes - Typos, formatting, slight revisions
• Update Content - Revisions, updating sections
• New Content - New features, sections, pages, tutorials
• Site and Tools - .clabot, version updates, maintenance, dependencies, new packages for the site (Docusaurus, Gatsby, React, etc.)

Ticket (if applicable)

Unify Sumo API Docs and API spec? (redocusaurus)

[JV0812]

@kimsauce This works perfectly for me in my local, can you please run the branch from your end and let me know what all modifications can be performed to make it much better.

[kimsauce]

Left comment here https://sumologic.atlassian.net/browse/DOCS-68?focusedCommentId=866460

[kimsauce]

Hey @JV0812 — ran this locally and made a few fixes, pushed to the branch:

1. Font override (sumo.scss)
The Redocusaurus config sets Inter, sans-serif as the font family, but Inter isn't loaded in our site — the API reference page was rendering in a browser fallback font instead of Lab Grotesque. Added a CSS override in sumo.scss targeting .redoc-wrap to force Lab Grotesque across the Redoc panel.

2. Build warning suppression (package.json)
yarn build was emitting a recurring SSG warning: "No 'p' element in scope but a 'p' end tag seen" on /docs/api-reference/. This is a Redoc rendering quirk — it stores HTML descriptions in a custom html="..." attribute on divs, and the HTML minifier incorrectly parses the </p> tags inside as orphaned HTML. The underlying issue is in how Redoc renders, so it can't be fixed in our codebase. Added DOCUSAURUS_IGNORE_SSG_WARNINGS=true to the build script to suppress it.

3. Merge conflict (yarn.lock)
Resolved a conflict with main in yarn.lock — accepted main's lockfile and re-ran yarn install to regenerate with redocusaurus included.

Also worth noting: redocusaurus@2.5.0 has unmet peer dependencies on @docusaurus/theme-common@^3.6.0 and @docusaurus/utils@^3.6.0 (our site is on an older version). Not blocking now but could surface after a Docusaurus upgrade.

— via Claude Code

[kimsauce]

A few questions/suggestions on the API reference strategy:

Duplication with api.sumologic.com
The new /docs/api-reference/ page and api.sumologic.com are showing the same OpenAPI spec — one embedded, one external. The existing /docs/api/ pages (the per-category narrative docs) aren't the issue since those serve a different purpose (usage guides, code examples, auth context). The potential confusion is users finding both the embedded page and the external URL and wondering which is authoritative.

Since the whole point of this PR is keeping users in the doc site, I'd suggest the embedded version replaces api.sumologic.com as the go-to reference rather than sitting alongside it. No need to add a link to api.sumologic.com from the new page.

Keeping the spec in sync
The bigger long-term risk: static/sumologic-api.yaml will drift from api.sumologic.com if there's no process to keep it updated. Is there a plan for that? If the spec is auto-generated somewhere upstream, this should be wired into that pipeline.

Gradual migration suggestion
Once this is merged, we could update the individual /docs/api/ pages over time to point to /docs/api-reference/ instead of api.sumologic.com — that would make the embedded version the single source of truth within the doc site.

— via Claude Code

[kimsauce]

A few more updates pushed to the branch:

Font fix (docusaurus.config.js)
Changed fontFamily from Inter, sans-serif to "Lab Grotesque", sans-serif and headings from Metropolis Semi Bold, sans-serif to "Lab Grotesque", "Segoe UI". Neither Inter nor Metropolis are loaded in our site — the page was falling back to a browser default font. Lab Grotesque is our site font, defined via @font-face in sumo.scss. Also removed a CSS override I had added earlier in favor of setting it correctly in the config.

Intro note added to sumologic-api.yaml
Added a brief sentence to the info.description in the YAML spec so users landing on /docs/api-reference/ understand this is the interactive reference embedded in the doc site. Since this is a local copy of the spec, the note only appears on our embedded page and not on api.sumologic.com.

Important — keeping the YAML spec in sync
static/sumologic-api.yaml is a static copy, which means it will go stale every time the API spec is updated. You'll need a process to keep it current — ideally an automated sync from the source repo (sanyaku) whenever the spec changes, or at minimum a GitHub Actions workflow or alert that notifies the docs team when the spec is updated upstream so we can pull in the latest version. Without this, the embedded reference will drift from the live API and could show outdated endpoints to users.

— via Claude Code

[kimsauce]

Build script change (package.json)
Added DOCUSAURUS_IGNORE_SSG_WARNINGS=true to the build script. This suppresses a warning that appears on every yarn build caused by Redoc rendering HTML descriptions into a custom html="..." attribute on divs — the HTML minifier incorrectly parses the </p> tags inside that attribute as orphaned HTML elements. The warning is a Redoc rendering quirk that can't be fixed in our codebase, so suppressing it keeps the build output clean.

— via Claude Code