fix(docs): link documented data types from the API reference - #12334
Merged
mergify[bot] merged 1 commit intoAug 6, 2026
Conversation
The engine flags a schema node as a documented data type, and on the configuration side `ConfigOptions` turns that flag into a link to the matching section of the data-types page. The API reference publishes the same flag and did nothing with it: `BatchStatus.code` rendered its twelve values with no explanation and no pointer to the section that explains them — the state documenting it was meant to fix, on the page a reader most likely arrives from. That left the convention enforcing something nobody consumed. The build fails when a marked title has no matching heading, so the anchor was being maintained for a link the API side never rendered. Render "see <data type>" beside the values. The values stay: an API consumer needs to know what a field accepts, and the marker only says their meaning is written up elsewhere. The type label is deliberately left alone. Substituting a title for the accepted values there is exactly the regression that hoisting shared enums into components caused for fifteen query parameters, and a marked type used as a parameter would reintroduce it. The flag is read from the referring node as well as the `$ref` target, because pydantic publishes it inline for an inlined type and as a `$ref` sibling for a hoisted one. Part of MRGFY-8330 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Change-Id: I23de38ed505614420d6ca72d376424621b1c9c7a
Contributor
Merge Protections🟢 All 6 merge protections satisfied — ready to merge. Show 6 satisfied protections🟢 🤖 Continuous Integration
🟢 👀 Review Requirements
🟢 Enforce conventional commitMake sure that we follow https://www.conventionalcommits.org/en/v1.0.0/
🟢 🔎 Reviews
🟢 📕 PR description
🟢 🚦 Auto-queueWhen all merge protections are satisfied, this pull request will be queued automatically. |
There was a problem hiding this comment.
Pull request overview
This PR updates the API reference renderer to consume the existing “documented data type” marker in the OpenAPI schema by adding a small “see <data type>” link next to enum value lists, pointing to the corresponding section on /configuration/data-types.
Changes:
- Add a
dataTypeLinkHtml()helper to conditionally render a “see …” link for enum properties flagged as documented data types (including when the flag is on the$refsibling). - Extend schema enum rendering to append this link while keeping enum values visible.
- Add Vitest coverage to ensure flagged enums link correctly and unflagged enums remain unchanged (including a regression test against the real published API schema).
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| src/components/ApiReference/openapi.ts | Adds conditional “see data type” link rendering for flagged enum properties in the API schema HTML output. |
| src/components/ApiReference/openapi.test.ts | Adds tests validating link rendering behavior for flagged/unflagged enums and $ref-sibling markers, plus a real-schema regression check. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
kozlek
marked this pull request as ready for review
August 6, 2026 14:34
remyduthu
approved these changes
Aug 6, 2026
JulianMaurin
approved these changes
Aug 6, 2026
Contributor
Merge Queue Status
This pull request spent 2 minutes 54 seconds in the queue, including 2 minutes 29 seconds running CI. Required conditions to merge
|
60 tasks
mergify
Bot
deleted the
devs/kozlek/devs/kozlek/api-data-type-links/link-documented-data-types-api-ref--23de38ed
branch
August 6, 2026 15:06
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
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.
The engine flags a schema node as a documented data type, and on the
configuration side
ConfigOptionsturns that flag into a link to thematching section of the data-types page. The API reference publishes the
same flag and did nothing with it:
BatchStatus.coderendered its twelvevalues with no explanation and no pointer to the section that explains
them — the state documenting it was meant to fix, on the page a reader
most likely arrives from.
That left the convention enforcing something nobody consumed. The build
fails when a marked title has no matching heading, so the anchor was
being maintained for a link the API side never rendered.
Render "see " beside the values. The values stay: an API
consumer needs to know what a field accepts, and the marker only says
their meaning is written up elsewhere.
The type label is deliberately left alone. Substituting a title for the
accepted values there is exactly the regression that hoisting shared
enums into components caused for fifteen query parameters, and a marked
type used as a parameter would reintroduce it.
The flag is read from the referring node as well as the
$reftarget,because pydantic publishes it inline for an inlined type and as a
$refsibling for a hoisted one.
Part of MRGFY-8330
Co-Authored-By: Claude Opus 5 (1M context) noreply@anthropic.com