docs: unify Hub, DVP, and Registry API references - #26048
Draft
dvdksn wants to merge 13 commits into
Draft
Conversation
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
github-actions
Bot
added
area/api
Example lookup skipped annotations on intermediate schema references, incorrectly reporting valid examples as missing. Follow each reference in sequence and retain the external resource base, with regression coverage for annotation precedence, false and zero values, and cycles.
The API migration baseline mixed missing descriptions and examples with unresolved response contracts. Complete parameter descriptions, quote 2FA codes, and add examples based on documented fields without changing API constraints. Remove 121 resolved entries and group the remaining 168 by the evidence needed before merge.
Correct object and null handling, distinguish month/week alternatives, and complete metadata definitions and response examples. Remove the remaining DVP validation exceptions and add regression coverage. Keep the tooling README focused on build commands, validation, and maintenance.
dvdksn
force-pushed
the
codex/api-reference-implementation
branch
from
September 9, 2026 13:38
fd1ce31 to
51033c3
Compare
Correct Hub response shapes, nullable fields, token examples, and SCIM contracts. Keep Registry scoped to its documented endpoints while expressing authentication and media negotiation through OpenAPI fields. Remove the validation exception baseline, render text examples without JSON escaping, and verify corrected contracts and HTML/Markdown example parity.
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.
@netlify /reference/api/
Preview the API reference
Adds a shared API reference experience for Hub, DVP, and Registry: a catalog, operation navigation, linked schemas, request and response examples, and matching HTML and Markdown output. A validation and generation pipeline prepares the reference data for Hugo and runs as part of Docker and Netlify builds.
Migrates the three specifications to OpenAPI 3.2, correcting response shapes, nullable fields, and authentication and token examples. The Hub migration also corrects SCIM contracts and CSV exports; DVP gains complete report response schemas and examples. Registry keeps its documented Hub-specific subset, with authentication and media negotiation expressed through OpenAPI security and content fields.
Validation is strict for both checks and generation, with no exception baseline or bypass flag. The build uses the migrated sources directly, without migration scripts or records.
Page and specification URLs remain stable, including the DVP alias. Operation and schema anchors change. Engine and Governance retain their existing references.
Validated locally with Go tests, strict validation of all three specifications (zero diagnostics), scoped formatting and lint, and a full Hugo build checking all 176 HTML/Markdown page pairs, example parity, reference links, and byte-identical published specifications. A browser check confirmed raw CSV rendering and the generated request header. No live API requests were made.