docs: add v3 GraphQL API reference - #171
Open
PJ Tatlow (pjtatlow) wants to merge 2 commits into
Open
Conversation
Add the v3 GraphQL API to the Mintlify docs site alongside the v2 REST API, using a version picker (v2 (REST) default, v3 (GraphQL) tagged Beta). The reference is generated from a vendored doc model (redo/api-schema-v3/v3.docs.json) emitted by the v3 server's Pothos schema walk: - tools/graphql generator (`bazel run graphql_gen`): renders the model to MDX — one page per query/mutation/type, grouped by category, with a Stripe/Shopify-style expandable field explorer (linked types, per-field scopes, cycle-guarded nesting). It also patches the v3 nav in docs.json and validates the model's referential integrity (//tools/graphql:validate_test). Empty categories are skipped until they have content. - Hand-authored Getting Started pages: introduction, authentication, queries & mutations, pagination, rate limiting, errors. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Sort categories A-Z by label (instead of the model's order field), and sort queries, mutations, and objects alphabetically within each category in the nav and overview pages. Co-Authored-By: Claude Opus 4.8 (1M context) <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
1 participant
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
Adds the v3 GraphQL API to the Mintlify docs site alongside the existing v2 REST API. The API Reference tab now has a version picker — v2 (REST) (default) and v3 (GraphQL) with a Beta tag.
The entire reference is generated from a vendored doc model (
redo/api-schema-v3/v3.docs.json) that the v3 server emits from its Pothos schema walk (bazel run //redo/public/v3/server:emit_docsin the main repo). To regenerate here: re-vendor the JSON and runbazel run graphql_gen.What's included
tools/graphql/,bazel run graphql_gen): renders the doc model to MDX — one page per query / mutation / type, grouped by category, with:ResponseField+ nestedExpandable), linked types, per-fieldRequires:scopes, and cycle-guarded nesting (MAX_DEPTH)docs.json(preserving the hand-authored Getting Started group + the Beta tag)//tools/graphql:validate_test); empty/forward-declared categories are skipped and loggedthrottleStatus,429/THROTTLED), errors.Validation
bazel test tools/lint:lint_test— passesbazel test //tools/graphql:validate_test— passesmintlify broken-links— no broken linksNotes
build.yml) does not deploy the Mintlify site — that's handled by the Mintlify GitHub app. This PR only affects the Mintlify docs (redo/docs,docs.json), not the Stoplightpublish_docsjob.v3.docs.jsonregeneration in the main repo (redoapp/redo) should be merged too, so the source of truth matches what these docs were built from.🤖 Generated with Claude Code