Publish SwarmCommon.yaml so the served OpenAPI spec can be dereferenced - #841
Open
crtahlin wants to merge 1 commit into
Open
Publish SwarmCommon.yaml so the served OpenAPI spec can be dereferenced#841crtahlin wants to merge 1 commit into
crtahlin wants to merge 1 commit into
Conversation
The prebuild step copies openapi/Swarm.yaml to static/openapi.yaml but not its sibling openapi/SwarmCommon.yaml, which holds every schema, parameter, header and response. All 446 $refs in the published spec point at that one file, so the spec served from docs.ethswarm.org/openapi.yaml cannot be dereferenced by any OpenAPI client: 99 schemas, 23 parameters, 7 headers and 8 responses are unreachable. The Redoc page at /api/ is unaffected because redocusaurus resolves the refs at build time from the openapi/ directory, where both files sit together. That is why the failure is invisible: the human page renders and the published file still returns HTTP 200. Also publishes .well-known/agent.json as a copy of agent-card.json, so clients probing the spec-canonical A2A filename find the card, and adds scripts/validate-openapi-spec.mjs to the prebuild chain. The validator resolves every $ref in the published spec and exits non-zero if any fails, so this regression cannot return silently. Verified against both states: it fails with 446 unresolvable refs before the fix and passes after. Both generated files are gitignored, keeping openapi/ and agent-card.json the single sources of truth.
✅ Deploy Preview for test-twitter-preview-testing-3 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
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.
https://docs.ethswarm.org/openapi.yamlreturns HTTP 200 but cannot be dereferenced by any OpenAPI client. This makes it usable.Why
The prebuild step copies
openapi/Swarm.yaml→static/openapi.yaml, but not its siblingopenapi/SwarmCommon.yaml, which holds 99 schemas, 23 parameters, 7 headers and 8 responses. All 446$refs in the published spec point at that one file, and it is not published, so every one of them dangles.What that means in practice for anyone pointing a tool at the URL:
openapi-generator/swagger-codegenThe consequence worth caring about is not "the file is malformed" but that the spec never states
swarm-postage-batch-idis a required header. Someone generating a client gets code that compiles, calls the API, and receives a 400 with no indication why.The Redoc page at
/api/is unaffected, which is why this went unnoticed: redocusaurus resolves the refs at build time from theopenapi/directory where both files sit together. The human page renders correctly while the published file — the one machines fetch — is broken and still returns 200.What changed
package.json— the prebuild copy step also publishesSwarmCommon.yaml, and.well-known/agent.jsonas a copy ofagent-card.jsonso clients probing the spec-canonical A2A filename find the card instead of a 404..gitignore— both new outputs are generated, not committed, soopenapi/andagent-card.jsonremain the single sources of truth and cannot drift.scripts/validate-openapi-spec.mjs(new) — resolves every$refin the published spec and exits non-zero if any fails. Deliberately stricter thanvalidate-llms-txt.mjs, which is warning-only: a spec no client can dereference is broken output rather than a documentation warning. Without this the regression returns silently, since the broken file still serves 200.All refs resolve because they are bare relative references (
SwarmCommon.yaml#/…) and both files land at the site root.Verified both directions
Swarm.yaml(current behaviour)$refs resolveOutputs:
openapi.yaml87,639 b,SwarmCommon.yaml37,475 b,agent.jsonbyte-identical toagent-card.json.Caveats
/openapi.jsonis deliberately not included. Under this approach it would be a JSON file whose refs still point into a.yaml, which needs ref-rewriting — effectively bundling. Better handled by a@redocly/cli bundlestep later; tracked in ethersphere/DevRel#904.docusaurus buildwas not run locally (it needs network for the awesome-swarm and cheatsheet fetches). The validator was exercised directly against both states instead. Worth watching CI, since this PR adds a step that can fail the build.Addresses ethersphere/DevRel#904.
Description generated with help of AI.