[AS-333] Tech note: Wire up router.yaml autocomplete in your IDE

[ilan-bel]

Summary

Adds docs/router-config-schema-in-ide.md — Day 0 setup for VS Code, JetBrains, and Neovim/Vim to get router.yaml autocomplete, hover-help, and inline validation from the schema published with each Router release.

Includes the inline # yaml-language-server: $schema= directive as a fallback when project settings can't be edited.

Tracks AS-333.

Test plan

• Renders cleanly
• Schema URL works against the latest Router release
• VS Code / JetBrains / Neovim setup steps are accurate

🤖 Generated with Claude Code

[apollo-solutions-reviewer]

The IDE setup mechanics are sound, but the schema URL the whole guide depends on is wrong, which fails the ticket's acceptance criterion that the URL be current, accessible, and confirmed correct.

The doc instructs users to point their IDE at https://raw.githubusercontent.com/apollographql/router/v2.10.0/dev-docs/router_config.schema.json. That path does not exist. At the v2.10.0 tag, dev-docs/ contains no router_config.schema.json (only the review-notes, metrics, logging, telemetry-selectors, yaml-design-guidance, etc. files), so the raw URL 404s. The Router does not commit a generated config schema into the source tree; it is produced from the Rust config structs. Every code block in this guide reuses that same dead URL, so as written none of the VS Code, JetBrains, or Neovim setups will resolve a schema.

Before merge, confirm where the schema actually ships for a given release and point every example at it. The v2.10.0 GitHub release assets are only the platform binaries and checksum files; there is no router_config.schema.json asset there either. Verify the real, fetchable location (release artifact, docs-hosted URL, or router config schema CLI output) against a clean machine and update the doc, since the schema source is the load-bearing claim.

Secondary: the verification step gh release view --repo apollographql/router | head -3 is not a reliable way to read the latest tag; gh release view prints a title/metadata block whose first lines do not consistently surface the tag. Prefer gh release list --repo apollographql/router --limit 1 or gh release view --repo apollographql/router --json tagName.

Minor: the "See also" link uses the legacy docs/router/configuration/overview path; current Router config reference lives under the graphos/routing docs tree. Worth updating to avoid sending users to a redirect or stale page.

CI: the only check (Secrets in Source) passed. No prior reviews.

[apollo-solutions-reviewer]

This URL 404s. At the v2.10.0 tag there is no dev-docs/router_config.schema.json in the Router repo, and it is not a release asset either. Confirm the real schema location and update this URL; every example below reuses it, so all three IDE setups currently point at a dead schema.

[apollo-solutions-reviewer]

Verified at da6e2e5: the dead raw.githubusercontent.com schema URL is gone. The doc now states the schema is not published as a URL or release asset and has users generate it locally with router config schema > .apollo/router-config-schema.json, then points every IDE example (VS Code, JetBrains, Neovim, inline directive) at the committed ./.apollo/router-config-schema.json. This matches the supported workflow in the Router CLI reference. This thread can be resolved.

[apollo-solutions-reviewer]

gh release view | head -3 does not reliably surface the tag name. Use gh release list --repo apollographql/router --limit 1 or gh release view --repo apollographql/router --json tagName.

[apollo-solutions-reviewer]

Verified at da6e2e5: the unreliable gh release view | head -3 tag check is gone. The doc now uses gh release list --repo apollographql/router --limit 1 for the latest tag and gh release view --repo apollographql/router --json tagName -q .tagName for the bare tag string, as suggested. This thread can be resolved.

[apollo-solutions-reviewer]

Legacy docs path. The current Router YAML config reference lives under the graphos/routing docs tree; this docs/router/configuration/overview URL should be updated.

[apollo-solutions-reviewer]

Verified at da6e2e5: the legacy docs/router/configuration/overview link is gone. The See also section now points at the graphos/routing tree: the YAML configuration reference at /docs/graphos/routing/configuration/yaml and the CLI reference at /docs/graphos/routing/configuration/cli. This thread can be resolved.

[apollo-solutions-reviewer]

Second pass at da6e2e5. All three items from the prior review are resolved.

1. The dead raw.githubusercontent.com schema URL is removed. The doc now generates the schema locally with router config schema > .apollo/router-config-schema.json and points every IDE example at the committed ./.apollo/router-config-schema.json. This is the supported workflow; the Router CLI reference documents ./router config schema > configuration_schema.json and confirms the schema is generated from the binary rather than published as a URL or release asset.
2. The unreliable gh release view | head -3 tag check is replaced with gh release list --repo apollographql/router --limit 1 and gh release view --repo apollographql/router --json tagName -q .tagName.
3. The legacy docs/router/configuration/overview link is replaced with graphos/routing paths (the YAML config reference and the CLI reference).

Non-blocking nit for a future edit: the Verifying it is wired section still says "Check the URL responds; paste it in a browser," which is a leftover from the old URL-based approach. The schema is now a local file, so this bullet no longer applies. Approving.