Skip to content

Add Go support to aspire docs api - #21173

Merged
David Pine (IEvangelist) merged 2 commits into
mainfrom
ievangelist-go-apphost-ga
Oct 29, 2026
Merged

David Pine (IEvangelist) merged 2 commits into
mainfrom
ievangelist-go-apphost-ga

Conversation

@IEvangelist

@IEvangelist David Pine (IEvangelist) commented Oct 20, 2026 •

Copy link
Copy Markdown
Member

Note

Depends on microsoft/aspire.dev#1917, which publishes the Go API reference this command reads. Not a merge blocker: this PR is safe to merge first, and until those pages are published the Go scope stays empty.

Description

Adds Go to aspire docs api, so list, search and get accept --language go and the go scope once aspire.dev publishes the Go API reference under /reference/api/go/**.

The Go reference deliberately mirrors the TypeScript route shape (module / item / member), so the CLI builds Go entries from sitemap path segments exactly the way it does for TypeScript. Page-body parsing is unchanged.

  • Adds ApiReferenceLanguages.Go, a go root scope and the /reference/api/go sitemap route.
  • TypeScript and Go share one module-based index builder (BuildModuleItems). C# is untouched.
  • Bumps IndexSchemaVersion from 1 to 2 so caches built by older CLIs rebuild (the schema version is part of the index fingerprint).
  • Updates docs/specs/api-docs-commands.md and docs/specs/cli-output-formats.md.
  • Covers Go in the index service, member markdown parser and sitemap parser tests.

This is safe to merge ahead of the docs. Until the site publishes /reference/api/go/**, the Go scope is empty (No API entries found), and C# and TypeScript output is unchanged.

This is the first step of the Go AppHost GA epic. The docs come first because the page shape drives what the parser has to understand.

Part of #21115

Validation

  • dotnet test --project tests/Aspire.Cli.Tests/Aspire.Cli.Tests.csproj --no-launch-profile -- --filter-class "*.ApiDocsIndexServiceTests" --filter-class "*.ApiMemberMarkdownParserTests" --filter-class "*.ApiSitemapParserTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true": 44 passed, 0 failed.
  • dotnet test --project tests/Aspire.Cli.Tests/Aspire.Cli.Tests.csproj --no-launch-profile -- --filter-class "*.DocsCommandTests" --filter-class "*.ApiDocsFetcherTests" --filter-class "*.ApiDocsCacheTests" --filter-class "*.ApiDocsSourceConfigurationTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true": 27 passed, 0 failed.
  • End to end against a local build of the aspire.dev release/17.0 site with the Go reference (docs__api__sitemapUrl=http://127.0.0.1:4399/sitemap-0.xml):
    • docs api list go returned 122 modules.
    • docs api list go/aspire.hosting.redis returned 17 entries and list go/aspire.hosting.redis/redisresource returned 9 members.
    • docs api search "redis password" --language go ranked go/aspire.hosting.redis/redisresource/withpassword first.
    • docs api get returned the served page content.
  • C# and TypeScript regression check against the same local site: docs api list csharp (186 entries) and docs api list typescript (146 entries) are identical between the previously installed CLI (17.0.0-preview.1) and this build.

Checklist

  • Is this feature complete?
    • Yes. Ready to ship.
    • No. Follow-up changes expected.
  • Are you including unit tests for the changes and scenario tests if relevant?
    • Yes
    • No
  • Did you add public API?
    • Yes
      • If yes, did you have an API Review for it?
        • Yes
        • No
      • Did you add <remarks /> and <code /> elements on your triple slash comments?
        • Yes
        • No
    • No
  • Does the change make any security assumptions or guarantees?
    • Yes
      • If yes, have you done a threat model and had a security review?
        • Yes
        • No
    • No

Index and browse the Go API reference alongside C# and TypeScript. Go uses the same module -> symbol -> member route layout as TypeScript, so the sitemap parser recognizes /reference/api/go routes and the index builder shares one module-based item builder between the two languages. The index schema version is bumped so caches built before Go routes existed are rebuilt. Go routes only appear once the docs site publishes them, so this is safe to ship ahead of the pages.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
@github-actions

Copy link
Copy Markdown
Contributor

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 21173

Or

  • Run remotely in PowerShell:
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 21173"

@github-actions

This comment has been minimized.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The narrowly scoped changes preserve existing indexing behavior and include focused regression coverage, with no identified blocking issues.

No open issues 🎉

What changed in this PR

Adds Go API reference discovery to the CLI as an initial step toward Go AppHost GA, ready for publication of the corresponding documentation.

Changes:

  • Adds Go routes and shares module-based indexing with TypeScript.
  • Invalidates older indexes through a cache schema bump.
  • Adds regression coverage and documents Go scopes and output.
File Description
tests/​Aspire.Cli.Tests/​Mcp/​ApiDocs/​ApiSitemapParserTests.cs Tests Go routes and prefix filtering.
tests/​Aspire.Cli.Tests/​Mcp/​ApiDocs/​ApiMemberMarkdownParserTests.cs Tests parser behavior with Go-shaped content.
tests/​Aspire.Cli.Tests/​Mcp/​ApiDocs/​ApiDocsIndexServiceTests.cs Covers Go indexing, retrieval, filtering, and cache migration.
src/​Aspire.Cli/​Documentation/​ApiDocs/​ApiSitemapParser.cs Registers the Go sitemap route.
src/​Aspire.Cli/​Documentation/​ApiDocs/​ApiDocsIndexService.cs Adds Go indexing and updates cache versioning.
docs/​specs/​cli-output-formats.md Documents the Go language value.
docs/​specs/​api-docs-commands.md Documents Go scopes and hierarchy.

Review effort: Balanced

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@IEvangelist
David Pine (IEvangelist) marked this pull request as draft October 20, 2026 13:29
@IEvangelist
David Pine (IEvangelist) marked this pull request as ready for review October 21, 2026 21:45
David Pine (IEvangelist) added a commit to microsoft/aspire.dev that referenced this pull request Oct 22, 2026
> [!NOTE]
> **Works with** microsoft/aspire#21173, the CLI support for `aspire
docs api --language go`. Neither PR blocks the other: that PR is safe to
land first, because the Go scope stays empty until these pages are
published.
>
> **Needed by** #1923 and #1924, whose links to `/reference/api/go/`
resolve only once this PR is on `release/17.0`.

## Summary

<!-- Describe what this pull request changes and why. -->

Adds a Go API reference at `/reference/api/go/**`, shaped like the
TypeScript reference: index, module, item and member pages as HTML and
`.md`, with sidebar, search and sitemap entries. This is the first step
of Go AppHost GA (microsoft/aspire#21115).

The reference goes first because its route and markdown shape is what
`aspire docs api` parses from the sitemap.

What changes:

- **Generator.** `AtsJsonGenerator` gains a Go mode (`--language go`).
It ports the Go SDK generator's naming and type rules (PascalCase, `(T,
error)` results, trailing `opts ...*XxxOptions`, pointers, `*List[T]`,
`*Dict[K,V]`) and reads the same `aspire sdk dump` JSON as the
TypeScript mode.
- **Pipeline.** `generate-ts-api-json.ps1` takes `-Language
typescript|go`. `pnpm update:go-api`, `update-integration-data.ps1` and
the normalizer handle Go data. `update-integration-data.yml` stages
`src/frontend/src/data/go-modules` and its timeout goes from 45 to 75
minutes, since the job now runs C#, TypeScript and Go passes.
- **Data.** 122 modules in `src/frontend/src/data/go-modules/` (5.75
MB), generated from the same package versions as `ts-modules`.
- **Site.** `go-*` utilities, a `GoMemberCard` component and
`reference/api/go/**` routes, plus registrations in the reference
sidebar, search, overview and dev hub. The dev hub gets a `Go API`
reference link, so the item count assertion in `dev-layout.spec.ts` goes
from 30 to 31.
- **Doc text.** Doc comments render through a `GoDocText` component.
Backtick spans are styled inline code. An `{@ats-ref}` marker links to
the type page, or to the package function page for an extension method,
when the target is in the same module, and stays styled code otherwise.
The markdown routes keep the code spans and render markers as plain
code, without links. CLR generic arity markers are stripped from method
names in both.
- **Sidebar casing.** The Reference, Deployment and Community topic
groups and the Reference overview title use sentence case ("Aspire
reference", "Aspire deployment", "Aspire community"), like "Aspire
integrations" and "Aspire dashboard".
- **Tests.** Generator tests for Go mode, vitest suites for routes,
markdown, doc text, search, sidebar and the whole seed (`pnpm
test:unit:go-api`), and Playwright specs for Go search and sidebar.
Existing cross-language specs also cover Go. The version-dropdown
scenario for Go is its own test in `filter-navigation.spec.ts`: the
existing test already uses 48 to 75 s of its 120 s budget on
`release/17.0` CI, so a fourth iteration would leave little margin.

Design notes:

- A module is the contributing NuGet package (for example
`Aspire.Hosting.Redis`), as in TypeScript. The Go SDK itself is one flat
package, so each module page states the import path.
- The pages carry no experimental or feature-flag notice. The Go AppHost
doesn't require a flag at GA (microsoft/aspire#21106).
- The Go code copies the TypeScript route and markdown logic into new
files and keeps edits to shared files additive, which limits conflicts
with the main to release sync. Consolidating the two is a follow-up on
`main`.
- The 24 `Aspire.Hosting.Azure.Provisioning.<Service>` proxy packages
are left out. They would add 72 MB (1.28x the TypeScript data) and their
pins are stale on `release/17.0`. The base
`Aspire.Hosting.Azure.Provisioning` package is included.

Not in this PR:

- `<ApiReference>` Go links and a Go option in the AppHost language
switcher. The switcher is hard-wired to `csharp|typescript` and needs Go
docs tabs first (microsoft/aspire#21112).
- `go-modules` in `merge-main-into-release.sh` `generated_dirs` and its
test. Add it after the post-GA swap, when `main` has Go data.
- Doc fidelity gaps, listed in the generator README: callback properties
on core DTOs render as `func(...any) any`, and foreign enums and
hand-written SDK types have no pages. A Go `IApiReferenceExporter`
(`aspire sdk export --language go`) would replace the dump-derived
signatures.

Notes:

- The data is 13.x-based until the 17.0 packages publish. The updater's
PR uses `--base main`, so refreshing 17.0 data needs a manual run and a
`release/17.0` base.
- Scheduled runs of the updater on `main` fail at
`generate-package-json.ps1:112` (`$_.apiReference` under StrictMode).
That is unrelated and untouched here.

## Third-party links and affiliations

<!--
List any third-party links added or changed by this pull request and
disclose any
material affiliation with the linked organizations, such as employment,
sponsorship, or ownership. Write "None" if this pull request doesn't add
or
change third-party links.
-->

None. No third-party links are hand-written in this PR. The generated Go
data carries the same upstream package and doc-comment URLs as the
existing `ts-modules` data: 13 distinct hosts, every one already present
there.

## Validation

<!-- List the checks you ran or explain why validation isn't needed. -->

The frontend commands run in `src/frontend` with `CI=1`. The unit, lint
and markdown crawl results below are for the final head. The local `pnpm
build` and Playwright results are from `d7d7633e41`, before the doc text
and sidebar casing commits. CI on the final head `e506f71a33` passed all
17 checks, including the frontend build and the six Playwright shards
(desktop, tablet and mobile Chromium, two shards each).

- `dotnet test
tests/AtsJsonGenerator.Tests/AtsJsonGenerator.Tests.csproj --nologo -v
q`: 113 passed.
- `pnpm test:unit:go-api`: 211 passed (14 files).
- `pnpm test:unit`: 1374 passed, 1 skipped (94 files).
- `pnpm lint`: no warnings.
- Every Go `.md` route crawled on a local dev server that includes this
branch: 3,130 pages (1 index, 122 module, 1,902 item, 1,105 member). All
return 200 `text/markdown` with no `{@` markers left and no unbalanced
backticks, and the crawled set equals what `getStaticPaths` generates.
- `pnpm build`: exit 0 in 16 min 51 s on a 28-core machine, 35,616
pages, internal links valid. The sitemap has 3,130 Go, 19,293 TypeScript
and 4,914 C# API URLs.
- `pnpm exec playwright test --project=desktop-chromium --retries=0` on
the Go specs and the specs extended for Go: 125 passed, 1 skipped.
- Full Playwright suite on desktop, tablet and mobile (535, 535 and 531
tests, the three projects running at once on one machine): 524, 488 and
484 passed. 12 tests failed across the three runs. The
`dev-layout.spec.ts` hub item count failed in all three and was a real
regression from the new `Go API` link; it is fixed in this PR. The other
9 failures were timeouts under that load (`dev-browse`,
`filter-navigation`, `gallery-search-contract` and one mobile
`dev-layout` test). Every failing test passed when rerun alone with
`--workers=1 --retries=0`, and `filter-navigation.spec.ts` passes in
full on all three projects after the version-dropdown split.
- Full regeneration of all 122 modules through `generate-ts-api-json.ps1
-Language go` and the normalizer matched the checked-in data with 0
diffs. After the Foundry fix below, `Aspire.Hosting` and
`Aspire.Hosting.Foundry` were regenerated again: core is byte-identical
and Foundry matches the committed file.
- `aspire docs api list|search|get` against a local build of this site,
using the CLI from microsoft/aspire#21173: `list go` returns 122
modules, `search "redis password" --language go` ranks
`go/aspire.hosting.redis/redisresource/withpassword` first, and C# and
TypeScript output is identical to the previous CLI.
- A review pass found one issue: composite exported values in
`Aspire.Hosting.Foundry` (201 `FoundryModels.*` entries) rendered as
multi-line JSON, which split markdown bullets across lines. Fixed in the
generator with a regression test, and a whole-seed vitest now guards
every module.

---------

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
David Pine (IEvangelist) added a commit to microsoft/aspire.dev that referenced this pull request Oct 22, 2026
> [!IMPORTANT]
> **Depends on:**
>
> - microsoft/aspire#21173: the CLI change that adds `go` to `aspire
docs api`, which these pages document.
> - #1917: the Go examples use routes from the Go API reference, which
exist on `release/17.0` only once that PR lands.
>
> Merge this PR after both.

## Summary

Documents Go support in `aspire docs api`. The CLI change adds `go` next
to `csharp` and `typescript`, so the command reference now lists it
wherever the other languages are enumerated. This is part of Go AppHost
GA (microsoft/aspire#21115).

- **`aspire docs api`, `list`, `get` and `search`:** `go` is added to
the language roots, the `--language` values, the scope table (`go`,
`go/<module>` and `go/<module>/<symbol>`) and the identifier examples
(for example `go/aspire.hosting.redis/addredis`). Each addition sits
next to the matching TypeScript text.
- **`get-started/aspire-skills.mdx`:** "C# and TypeScript API docs" now
includes Go.

The Go examples use routes from the Go API reference in #1917. Until
that PR lands, these pages describe routes that don't exist on
`release/17.0` yet, and the Go scope of `aspire docs api` stays empty.
The pages carry no "experimental" wording because they go live at the GA
docs swap, when the Go feature flag is removed (microsoft/aspire#21106).

Not changed: other "C# or TypeScript" text in the docs (`aspire init
--language`, the FAQ, `what-is-aspire` and the agent skill file) is
about AppHost languages, not API docs. `whats-new/aspire-17.mdx` doesn't
mention `aspire docs api` languages, so there's nothing to update there.

## Third-party links and affiliations

None.

## Validation

- Opened the seven Go routes used in the examples on a local preview of
#1917 and confirmed that each returns 200 as HTML and as its `.md` twin
(`go/`, `aspire.hosting`, `aspire.hosting.redis`, `addredis`,
`redisresource`, `redisresource/withpersistence` and
`aspire.hosting/withreference`). All seven are also in that build's
`sitemap-0.xml`. Nonexistent routes return an error on the same server,
so a 200 is meaningful.
- Compiled the five changed MDX files with the repo's `@mdx-js/mdx`. A
deliberately broken snippet is rejected, so the check can fail. Every
code fence has a language id.
- Checked the added lines against the repo's forbidden-words rules, and
ran `git diff --check`: both clean.
- Ran the three docs-scanning vitest files: 15 passed.

Not run: the full `pnpm lint`, `pnpm test:unit` and a site build. ESLint
doesn't lint MDX and the repo has no Markdown linter.

Co-authored-by: David Pine <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, David. This is a small, clean change with good coverage, and the schema-version bump is the right call. I'm approving with one request: please address the duplicate TypeScript/Go results in an unfiltered search (inline comment on ApiDocsIndexService.cs) before merge. The other comments are minor; they can be small updates before merge or follow-ups.

One more minor point outside the diff: the list scope help text (src/Aspire.Cli/Resources/ApiCommandStrings.resx, ScopeArgumentDescription) and the src/Aspire.Cli/README.md examples still mention only csharp/typescript. A go example would help discoverability (remember UpdateXlf and the .Designer.cs if the resx changes).

Comment thread docs/specs/api-docs-commands.md Resolved
- Break API search score ties by language (csharp, typescript, go) so a Go twin no longer outranks its TypeScript counterpart in unfiltered searches, and pin the order with a test.
- Describe symbol and member classification in the api docs spec the way module items are indexed.
- Rename the Go parser tests to say what they pin.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
@github-actions

Copy link
Copy Markdown
Contributor

Tests selector

2 / 100 PR test projects · 4 PR jobs, from 5 changed files.

Selected PR test projects (2 / 100)

Aspire.Cli.EndToEnd.Tests, Aspire.Cli.Tests

Selected PR jobs (4)

cli-starter-validation, extension-e2e, polyglot, typescript-api-compat


How these were chosen — grouped by what changed

📦 affected project Aspire.Cli
→ 1 test: Aspire.Cli.EndToEnd.Tests

🧪 tests/Aspire.Cli.Tests/Mcp/ApiDocs/ApiDocsIndexServiceTests.cs (changed test)
→ 1 directly: Aspire.Cli.Tests

🧪 tests/Aspire.Cli.Tests/Mcp/ApiDocs/ApiMemberMarkdownParserTests.cs (changed test)
→ 1 directly: Aspire.Cli.Tests

🧪 tests/Aspire.Cli.Tests/Mcp/ApiDocs/ApiSitemapParserTests.cs (changed test)
→ 1 directly: Aspire.Cli.Tests

Job reasons

Job Triggered by
cli-starter-validation affected project Aspire.Cli
extension-e2e • src/Aspire.Cli/Documentation/ApiDocs/ApiDocsIndexService.cs, src/Aspire.Cli/Documentation/ApiDocs/ApiSitemapParser.cs
• affected project Aspire.Cli
polyglot affected project Aspire.Cli
typescript-api-compat affected project Aspire.Cli

Selection computed for commit 7bc3116.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No blocking issues remain, and focused regression coverage supports the bounded indexing changes and preservation of existing language behavior.

No open issues 🎉

Review effort: Balanced

@github-actions

Copy link
Copy Markdown
Contributor

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

@IEvangelist
David Pine (IEvangelist) merged commit f4da584 into main Oct 29, 2026
393 of 396 checks passed
@microsoft-github-policy-service microsoft-github-policy-service Bot added this to the 17.0 milestone Oct 29, 2026
@aspire-repo-bot

Copy link
Copy Markdown
Contributor

✅ No documentation update needed.

docs_required → already documented by name. Triggered signal: pr_body_has_cli_flag_mention (--language go, go scope).

  • aspire-docs-api-search.mdx: "Supported values are csharp, typescript, and go." and example aspire docs api search "WithReference" --language go.
  • aspire-docs-api-list.mdx: "Start with a language root (csharp, typescript, or go)", table row | go | Top-level Go modules |, example aspire docs api list go.
  • aspire-docs-api-get.mdx: "go/aspire.hosting.redis/addredis".
  • aspire-docs-api.mdx: "The C#, TypeScript, and Go API hierarchies are supported."

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants