feat: generate error and warning documentation in the Mintlify API reference#1209
Open
dawnho wants to merge 7 commits into
Open
feat: generate error and warning documentation in the Mintlify API reference#1209dawnho wants to merge 7 commits into
dawnho wants to merge 7 commits into
Conversation
…ference Restore enumerated error/warning docs to the Mintlify API reference as one combined page per resource, mirroring the events-documentation pattern from #1204. Errors and warnings are discriminated-list properties on each resource that the OpenAPI spec can't express, so they were dropped in the GitBook to Mintlify migration. Adds mintlify-codegen/errors.ts (updateErrorPages), wires the pages into the sidebar via update-nav.ts (after the events page), and hooks it into generate.ts as Phase F.7, before link canonicalization. Generates 13 pages. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Open each Errors/Warnings section with the object shape — an example payload plus a properties accordion (error_code/warning_code, message, created_at, and the classification flags like is_device_error) — above the existing code list, mirroring how the events pages document payloads. Extract the shared property-rendering helpers (formatType, sampleValue, indent, hasEnumValues) into property-fields.ts, now used by both events.ts and errors.ts. Verified the events pages regenerate byte-identical. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Each error/warning code is now a heading (### for ungrouped codes, #### for codes nested under a variant-group heading) instead of bold text, so every code gets a stable, linkable anchor. Drops the --- separators the headings replace. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Separate each code (heading + description) with a horizontal rule so the long lists are easier to scan, restoring the divider rhythm from the original GitBook layout. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The example payload's `message` was populated from the doc description, which contains Markdown links that render as literal syntax inside a JSON code block. Strip link/inline-code Markdown to plain text (and fall back to a placeholder when the description is empty) so the example reads like a real API message. The code entry descriptions keep their Markdown links. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Wrap each section's example payload in <ResponseExample> so it renders in the right-hand sticky column, matching the object pages' two-column layout. The intro, properties accordion, and code list flow in the left column. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Restores enumerated error and warning documentation to the Mintlify API reference, mirroring the events-documentation pattern from #1204.
Errors and warnings are enumerated states Seam reports on a resource (e.g.
device.errors[].error_code = "device_offline"), each with a description. The blueprint models them as discriminated-list properties, but the OpenAPI spec can only express the genericerrors/warningsarray shape — so the enumerated codes and their meanings were dropped in the GitBook→Mintlify migration. This is the same gap events had before #1204.What's included
mintlify-codegen/errors.ts(updateErrorPages): walksblueprint.resources, extracts theerrors/warningsdiscriminated lists (code = discriminator enum value, prose = variant description), groups by variant group, and writes one combinederrors.mdxper resource with## Errorsand## Warningssections.update-nav.ts: addsisErrorsPage(so pages survive nav rebuilds), generalizesinsertAfterObjectPage→insertAfterPage+insertIntoGroups, and addsinsertErrorPagesIntoNavanchoring each page after its events page (sidebar reads object → events → errors).generate.ts: Phase F.7, after events and before link canonicalization (so legacydocs.seam.colinks in descriptions get rewritten).Resources with error data but no object page (bridge_client_session and three unmanaged ACS variants) are skipped with a log line — matching events behavior.
Test plan
npm run typecheck,npm run lint,npm run formatall passnpm run generate:mintlifyregenerates deterministically (13 pages; output stable across the code-simplify refactor)/api/devices/errorsrenders in the Mintlify dev server: grouped sub-headings appear in the on-page TOC and description links resolve🤖 Generated with Claude Code