feat(api): serve the REST OpenAPI spec at /openapi.json - #517
Merged
Conversation
![orca-security-eu[bot]](https://avatars.githubusercontent.com/in/276244?s=60&v=4){kind=small}
There was a problem hiding this comment.
Orca Security Scan Summary
| Status | Check | Issues by priority | |
|---|---|---|---|
 Passed |
Infrastructure as Code |  0  3  326  224 |
View in Orca |
| Passed |
SAST | 0 0 0 0 |
View in Orca |
| Passed |
Secrets | 0 0 0 0 |
View in Orca |
| Passed |
Vulnerabilities | 0 0 0 0 |
View in Orca |
🛡️ The following IaC misconfigurations have been detected
| NAME | FILE | ||
|---|---|---|---|
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
|
Invalid Format | ...eaviate-openapi.json | View in code |
| ... | ... | ... | ... |
g-despot
force-pushed
the
api/publish-openapi-spec
branch
from
August 17, 2026 09:08
e36c6eb to
f951bbb
Compare
g-despot
changed the title
g-despot
force-pushed
the
api/publish-openapi-spec
branch
from
August 17, 2026 11:39
f951bbb to
7327a05
Compare
The spec this site already renders was not reachable at any conventional URL, so agents and scanners following convention found nothing. Commit the 1.39.0 spec under static/specs/ and rewrite /openapi.json to it. That is the only path served — there is deliberately no /swagger.json alias. Swagger 2.0 is OpenAPI 2.0, so /openapi.json names the current document accurately and stays accurate if the spec is later converted to OpenAPI 3.x, where the alias would turn actively misleading: a 3.x document at /swagger.json is exactly what a Swagger-era client cannot consume. Served from a local file rather than proxied to raw.githubusercontent: a 200-proxy passes the origin's text/plain content-type through and Netlify header rules do not apply to proxied responses. That committed file is the single source of truth. The Scalar reference page at /weaviate/api/rest now reads it from /specs/weaviate-openapi.json rather than fetching a pinned branch from GitHub — the same wiring the Engram spec already uses — so the rendered reference and /openapi.json cannot serve different versions of the API, and there is no second pin to keep in sync. Refreshing the copy stays manual for now. The reasoning lives in static/specs/README.md — what the file is, how to refresh it, why it is served this way, and how to test the route locally — and netlify.toml keeps a five-line comment: what the rule does, do not turn it into a proxy, and a pointer to that README. On the API page the supporting detail — the alternative URL, versioning, and scope — moves into a collapsible, while the heading and the /openapi.json URL stay above it. <details> does not auto-expand on fragment navigation and the page deep-links this section from its own intro, so anything a reader must see on arrival cannot live inside the collapsible. Netlify rewrites do not exist for the plain static server behind `yarn validate-links-dev`, so /openapi.json 404s there while serving 200 in production. It is skipped in that lane, with the reason recorded; the un-rewritten /specs/weaviate-openapi.json is still linked from the API page and still crawled, so a missing spec file fails link validation.
g-despot
force-pushed
the
api/publish-openapi-spec
branch
from
August 17, 2026 11:53
7327a05 to
b29ac41
Compare
g-despot
added a commit
to weaviate/weaviate-io
that referenced
this pull request
Aug 17, 2026
…data Discovery: - add /.well-known/ai-catalog.json listing the documentation, spec, MCP and SDK resources agents need Markdown: - add frontmatter to the 33 existing .md twins - emit <link rel="alternate" type="text/markdown"> from a single route map, guarded by a build-time check that fails if a mapped twin is missing - add 8 twins for the case studies, company and community pages Metadata: - emit one site-wide Organization + WebSite JSON-LD with contactPoint and address, remove the homepage's own Organization + WebSite nodes so that block is the only definition, and scope the existing Japanese page entity so the two no longer collide - add FAQPage to /pricing, derived from the array the component renders - give the 404 page recovery links and machine-readable entry points static/.well-known/ai-catalog.json and static/llms.txt reference https://docs.weaviate.io/openapi.json, which is published by pending weaviate/docs#517 and 404s until that deploys. Shipping this first leaves those two content links dead in the meantime.
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.
Publishes the REST OpenAPI spec at
/openapi.json. It is the same spec the API reference page already renders — it just was not reachable at a conventional URL, so agents and scanners following convention found nothing.static/specs/weaviate-openapi.json— committed copy of the v1-39 spec (Swagger 2.0, 77 paths)netlify.toml— 200-rewrite of/openapi.jsonto the local filedocs/weaviate/api/index.mdx— links it_build_scripts/validate-links-pr.js— skips the rewritten path, since the link validator serves the build from a plain static server where netlify rewrites do not apply. The page also links/specs/weaviate-openapi.json, which the validator does check, so a deleted or renamed spec still fails CI.There is deliberately no
/swagger.jsonalias:/openapi.jsonnames the current document accurately (Swagger 2.0 is OpenAPI 2.0) and stays accurate if the spec is ever converted to OpenAPI 3.x, where the alias would turn misleading.Served from a local file rather than proxied to GitHub: a 200-proxy passes the origin's
text/plain+nosniffcontent-type through, and Netlify header rules do not apply to proxied responses. The rejected proxy rule is kept commented alongside the measurement that ruled it out.The spec branch is pinned twice — this copy and the Scalar
spec.url.static/specs/README.mddocuments the refresh; collapsing the two is a follow-up.