Repository navigation
fix(api): publish the contract and correct the 404 declaration (#113, #112) - #117
Merged
Merged
Conversation
The site is static. The host cannot build a per-path JSON error body, so every miss returns the site's own 404 page. The shared `NotFound` response declared `application/json` against the `Error` schema, which no request ever receives. All 12 record paths reach that response through `$ref`, so one edit corrects all of them. Keep the `Error` schema and mark it reserved for the dynamic resolver that `info.description` announces. It is the only unreferenced schema, and the comment says why it stays. Closes textrefs#113 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LTNUyMDUnkyBLHWac3qLjY
The site description advertised the contract file, but only the rendered HTML at `/api/` existed. `starlight-openapi` reads `api/openapi.yaml` at build time and copies nothing, so the advertised URL returned 404. A client could read the docs, but could not generate code, run contract tests, or import the API into a tool. Serve the file from a static endpoint. `?raw` inlines the source at build time, so the served body stays byte-identical and cannot drift from a copy. GitHub Pages sends `text/yaml` for the `.yaml` extension; the contract now records that, as it already records the `.jsonl` case. Closes textrefs#112 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LTNUyMDUnkyBLHWac3qLjY
`RegistryObject` and `Error` are the only schemas that no response uses. `Error` already carries its reason. This adds the second one: the union names what every dump line and every `@graph` member is, so a client can validate a record before it knows the record's type. Part of textrefs#113 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LTNUyMDUnkyBLHWac3qLjY
Member
Author
|
Review complete: no blocking findings.\n\nThe shared HTML 404 response matches the static-host behavior, the raw-import endpoint avoids a second contract copy, and the generated dist/api/openapi.yaml is byte-identical to api/openapi.yaml in my local build. npm run verify:fast passes on the checked-out head, and the full GitHub checks are green. |
This was referenced Aug 31, 2026
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.
Two findings from the API audit in #111. Both edit
api/openapi.yaml, so they land together. Review commit by commit.fix(api): declare the 404 response as text/html (#113, finding G3)
Every record path declared
404asapplication/jsonagainst theErrorschema. The site is static, so the host cannot build a per-path error body. It serves the site's HTML 404 page instead. The contract promised a body that the site never sends.NotFoundresponse now declarestext/html. All 12 record paths reach it through$ref, so one edit covers them.Errorschema stays, with a comment that says why: it describes the error body of the dynamic resolver thatinfo.descriptionalready announces. It is the only unreferenced schema.Evidence: GitHub Pages answers a missing path with
content-type: text/html; charset=utf-8.fix(api): publish the OpenAPI contract at /api/openapi.yaml (#112, finding G1)
astro.config.mjs:55advertised the contract file. The URL returned 404, becausestarlight-openapirenders HTML at/api/and copies nothing.src/pages/api/openapi.yaml.tsserves the file.?rawinlines the source at build time, so the body cannot drift from a copy inpublic/./api/index.info.descriptionrecords the served media type, in the same paragraph that records the.jsonlcase. GitHub Pages sendstext/yamlfor a.yamlfile — confirmed against two live Pages deployments (prometheus-community.github.io,grafana.github.io).Verification
npm run verify:fastpasses.cmp api/openapi.yaml dist/api/openapi.yamlexits 0: the served body is byte-identical.After deploy, confirm both with one request each:
Closes #113
Closes #112
🤖 Generated with Claude Code
https://claude.ai/code/session_01LTNUyMDUnkyBLHWac3qLjY