Repository navigation
Add Go API reference - #1917
Merged
David Pine (IEvangelist) merged 10 commits intoOct 22, 2026
Merged
Add Go API reference#1917
Conversation
Port the Go SDK generator's naming and type resolution into AtsJsonGenerator so it can emit go-modules JSON from the same capability dumps used for TypeScript. TypeScript output is unchanged. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Add a -Language go mode to generate-ts-api-json.ps1, a pnpm update:go-api script, Go terminology normalization, and wire Go generation into update-integration-data. The workflow allow-list and timeout cover the extra pass. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Generated with pnpm update:go-api from the package versions pinned in src/frontend/src/data/pkgs. The Aspire.Hosting.Azure.Provisioning.* proxy packages are omitted; see the AtsJsonGenerator README. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Add /reference/api/go routes mirroring the TypeScript reference (index, module, item and member pages plus .md twins), sidebar, API search, site search entry, the reference overview and dev hub cards, and unit and e2e coverage. Go pages are excluded from Pagefind like the other API reference pages. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Exported values whose Go type is a struct (the 201 FoundryModels.* entries) were emitted as the dump's indented JSON, including the line endings of the OS that produced it. That split each markdown bullet across several physical lines and made the generated data differ per platform. Serialize composite values as compact JSON in the generator, regenerate the Aspire.Hosting.Foundry seed (only the 201 value strings change), and add a whole-seed markdown test that fails when an exported value spans lines. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Member resolution produces incomplete or inaccurate Go references, and paired setters are missing from searchable fields.
1 open issue
What changed in this PR
Adds Go API reference support alongside C# and TypeScript, providing browser and Markdown documentation for Go AppHost APIs and CLI discovery.
Changes:
- Adds Go generation support, reference data, and update automation.
- Introduces Go routes, search, sidebar navigation, and discovery links.
- Extends unit and browser coverage for Go and cross-language behavior.
| File | Description |
|---|---|
| tests/AtsJsonGenerator.Tests/ConsoleCapture.cs | Defines shared console-capture collection. |
| tests/AtsJsonGenerator.Tests/AtsJsonGeneratorTests.cs | Serializes console-capturing tests. |
| src/tools/AtsJsonGenerator/README.md | Documents Go generation and limitations. |
| src/tools/AtsJsonGenerator/Helpers/Models.cs | Extends dump metadata models. |
| src/tools/AtsJsonGenerator/Helpers/GoNaming.cs | Implements Go naming rules. |
| src/tools/AtsJsonGenerator/Helpers/GoKnownTypes.cs | Resolves supporting-package type names. |
| src/tools/AtsJsonGenerator/Helpers/AtsTypeCategories.cs | Defines dump type categories. |
| src/tools/AtsJsonGenerator/Helpers/AtsTransformer.cs | Shares transformation helpers. |
| src/tools/AtsJsonGenerator/BatchGenerateCommand.cs | Adds batch language selection. |
| src/frontend/tests/unit/navigation-preferences.vitest.test.ts | Covers Go navigation preferences. |
| src/frontend/tests/unit/go-modules-cache.vitest.test.ts | Tests collection caching. |
| src/frontend/tests/unit/go-member-card.vitest.test.ts | Tests Go member rendering. |
| src/frontend/tests/unit/go-api-sidebar.vitest.test.ts | Tests Go sidebar structure. |
| src/frontend/tests/unit/go-api-routes-reference.ts | Provides route-equivalence oracle. |
| src/frontend/tests/unit/go-api-route-catalog.vitest.test.ts | Checks catalog routes and links. |
| src/frontend/tests/unit/api-search-recovery.vitest.test.ts | Extends recovery coverage to Go. |
| src/frontend/tests/unit/api-search-lifecycle.vitest.test.ts | Extends search lifecycle coverage. |
| src/frontend/tests/unit/api-reference-routes.vitest.test.ts | Tests Go route canonicalization. |
| src/frontend/tests/e2e/site-search.spec.ts | Tests Go search handoff and keyboard navigation. |
| src/frontend/tests/e2e/search-visual-parity.spec.ts | Includes Go search styling. |
| src/frontend/tests/e2e/og-metadata.spec.ts | Checks Go social-image fallback. |
| src/frontend/tests/e2e/mobile-ux.spec.ts | Covers responsive Go pages. |
| src/frontend/tests/e2e/go-api-sidebar.spec.ts | Tests Go sidebar navigation. |
| src/frontend/tests/e2e/go-api-search.spec.ts | Tests Go search results. |
| src/frontend/tests/e2e/filter-navigation.spec.ts | Adds separate Go filter scenario. |
| src/frontend/tests/e2e/dev-layout.spec.ts | Updates hub link-count expectation. |
| src/frontend/tests/e2e/api-search-contract.spec.ts | Adds Go search contract coverage. |
| src/frontend/tests/e2e/api-markdown-routes.spec.ts | Checks Go Markdown endpoints. |
| src/frontend/tests/e2e/api-cross-language-navigation.spec.ts | Covers navigation involving Go. |
| src/frontend/src/utils/go-api-sidebar.ts | Builds Go sidebar trees. |
| src/frontend/src/utils/go-api-search.ts | Builds Go search entries. |
| src/frontend/src/utils/go-api-search-stats.ts | Calculates Go catalog statistics. |
| src/frontend/src/utils/go-api-function-kind.ts | Classifies Go callables and identities. |
| src/frontend/src/utils/api-reference-routes.ts | Normalizes Go sidebar anchors. |
| src/frontend/src/styles/site.css | Sets Go sidebar width. |
| src/frontend/src/pages/reference/api/go/[module]/[item]/[member]/index.astro | Renders HTML member pages. |
| src/frontend/src/pages/reference/api/go/[module]/[item]/[member].md.ts | Generates Markdown member pages. |
| src/frontend/src/pages/reference/api/go/[module]/[item].md.ts | Generates Markdown item pages. |
| src/frontend/src/pages/reference/api/go/[module].md.ts | Generates Markdown module pages. |
| src/frontend/src/pages/reference/api/go.md.ts | Serves the Markdown index. |
| src/frontend/src/data/go-modules/CommunityToolkit.Aspire.Hosting.Umami.13.5.0.json | Adds Umami API data. |
| src/frontend/src/data/go-modules/CommunityToolkit.Aspire.Hosting.Squad.13.5.0.json | Adds Squad API data. |
| src/frontend/src/data/go-modules/CommunityToolkit.Aspire.Hosting.Rust.13.5.0.json | Adds Rust hosting API data. |
| src/frontend/src/data/go-modules/CommunityToolkit.Aspire.Hosting.Redis.Extensions.13.5.0.json | Adds Redis extension API data. |
| src/frontend/src/data/go-modules/CommunityToolkit.Aspire.Hosting.Python.Extensions.13.5.0.json | Adds Python extension API data. |
| src/frontend/src/data/go-modules/CommunityToolkit.Aspire.Hosting.PowerShell.13.5.0.json | Adds PowerShell API data. |
| src/frontend/src/data/go-modules/CommunityToolkit.Aspire.Hosting.MongoDB.Extensions.13.5.0.json | Adds MongoDB extension API data. |
| src/frontend/src/data/go-modules/CommunityToolkit.Aspire.Hosting.Keycloak.Extensions.13.5.1-beta.895.json | Adds Keycloak extension API data. |
| src/frontend/src/data/go-modules/CommunityToolkit.Aspire.Hosting.Flyway.13.5.0.json | Adds Flyway API data. |
| src/frontend/src/data/go-modules/CommunityToolkit.Aspire.Hosting.Elasticsearch.Extensions.13.5.0.json | Adds Elasticsearch extension API data. |
| src/frontend/src/data/go-modules/CommunityToolkit.Aspire.Hosting.DuckDB.13.5.0.json | Adds DuckDB API data. |
| src/frontend/src/data/go-modules/CommunityToolkit.Aspire.Hosting.Deno.13.5.0.json | Adds Deno API data. |
| src/frontend/src/data/go-modules/CommunityToolkit.Aspire.Hosting.Dbx.13.5.0.json | Adds Dbx API data. |
| src/frontend/src/data/go-modules/CommunityToolkit.Aspire.Hosting.Bun.13.3.0.json | Adds Bun API data. |
| src/frontend/src/data/go-modules/CommunityToolkit.Aspire.Hosting.Adminer.13.5.0.json | Adds Adminer API data. |
| src/frontend/src/data/go-modules/Aspire.Hosting.Browsers.13.6.0-preview.1.26478.8.json | Adds browser hosting API data. |
| src/frontend/src/data/go-modules/Aspire.Hosting.Azure.Search.13.6.0.json | Adds Azure Search API data. |
| src/frontend/src/data/go-modules/Aspire.Hosting.Azure.OperationalInsights.13.6.0.json | Adds Log Analytics API data. |
| src/frontend/src/data/go-modules/Aspire.Hosting.Azure.FrontDoor.13.6.0-preview.1.26478.8.json | Adds Front Door API data. |
| src/frontend/src/data/go-modules/Aspire.Hosting.Azure.ApplicationInsights.13.6.0.json | Adds Application Insights API data. |
| src/frontend/src/data/dev-hub.ts | Links Go APIs from the hub. |
| src/frontend/src/content/docs/reference/overview.mdx | Adds Go reference discovery card. |
| src/frontend/src/content.config.ts | Registers the Go collection. |
| src/frontend/src/components/starlight/Sidebar.astro | Recognizes Go reference pages. |
| src/frontend/src/components/starlight/Search.astro | Adds Go API search link. |
| src/frontend/src/components/api-reference/search-lifecycle.ts | Supports Go search lifecycle registration. |
| src/frontend/scripts/update-go-api.ts | Orchestrates Go data regeneration. |
| src/frontend/scripts/normalize-generated-api-data.ts | Normalizes Go documentation terminology. |
| src/frontend/package.json | Adds Go update and test commands. |
| src/frontend/config/sidebar/reference.topics.ts | Adds localized Go navigation links. |
| .github/workflows/update-integration-data.yml | Stages Go data and increases timeout. |
| .github/instructions/astro.instructions.md | Documents the Go collection. |
| .agents/skills/update-integrations/SKILL.md | Documents Go regeneration workflow. |
Review effort: Balanced
Contributor
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
A marker interface declares no methods in Go; its functions are declared on the concrete types they apply to. The Go API reference now says so on the marker's item and member pages (HTML and Markdown): a method page defines the function with its receiver (`func (Resource) ExcludeFromManifest() Resource`) instead of inside an interface fence, the Defined on entry is labelled `marker`, one shared GO_MARKER_NOTE explains the relationship, and member pages list the types the function applies to. Routes, slugs, anchors, headings used by the CLI Markdown parser, page counts, search and sitemap entries are unchanged, as is every TypeScript and C# page. Member resolution (functions whose appliesTo includes a handle) is intentionally left alone: each variant that adds those pages grows the Go member pages by far more than 5%, and the TypeScript reference has the same shape. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
This was referenced Oct 20, 2026
David Pine (IEvangelist)
marked this pull request as draft
October 20, 2026 13:29
Go API descriptions carry single-backtick code spans, fenced spans, markdown links, and {@ats-ref} tokens that were printed as raw text. GoDocText parses them into styled inline code, links, and in-module type and method links that resolve to the Go route. A target with no Go page renders as non-link code. Search rows and markdown output share the same parser.
Remove the experimental note, which no longer applies to the Go AppHost SDK, and fix the landing page intro that ran two sentences together.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Method names in the Go API descriptions carry the CLR arity with two backticks, for example `WithModTidy``1`. The inline code pattern only allowed one, so the name rendered as a code span followed by a stray code span holding the arity digit. Both the type and the method arity forms are now read as one span and shown without the arity. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
Matches the neighboring API reference and CLI reference groups. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
…e overview title Aligns Aspire community, Aspire deployment and the Reference overview page title with the sentence-case Aspire reference group. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: c8717a87-0ee5-4296-a6fd-ea6e2d91a57e
4 of 14 tasks
David Pine (IEvangelist)
marked this pull request as ready for review
October 21, 2026 21:45
David Pine (IEvangelist)
added a commit
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
David Pine (IEvangelist)
added a commit
that referenced
this pull request
Oct 22, 2026
…ces (#1924) > [!IMPORTANT] > **Depends on:** > > - microsoft/aspire#21193: `go-apphost.mdx` shows what `aspire new aspire-go-starter` writes, and the `.gitignore` that lists `.aspire/` and the handle checks in the `apphost.go` fence come from that PR. Merge this PR after it. > - #1917: links to `/reference/api/go/` resolve only once the Go API reference is on `release/17.0`. > - microsoft/aspire#21183: these pages document Go without a feature flag, but the CLI still requires the flag until that PR merges. The pages go live at the GA docs swap, after the flag is removed. ## Summary Adds Go AppHost documentation next to the existing C# and TypeScript pages. This is the docs and samples child (microsoft/aspire#21112) of Go AppHost GA (microsoft/aspire#21115). The content goes live at the GA docs swap, because it targets `release/17.0`. New pages, each with its sidebar entry in the same commit: - **`app-host/go-apphost`:** getting started. Prerequisites, creating a Go AppHost with `aspire new` and `aspire init`, running it, the `apphost.go` and `aspire.config.json` layout, the generated SDK and restore, adding integrations, orchestrating apps in other languages, and debugging. - **`app-host/go-apphost-conventions`:** how the Go API differs from C#: names and handles, optional parameters, the error model, and cancellation. Edited pages: - **`languages-and-runtimes/index.mdx` and `architecture/multi-language-architecture.mdx`:** Go is listed and explained next to TypeScript. - **`integrations/frameworks/go/go-host.mdx` and `go-get-started.mdx`:** `go-host.mdx` gets Go AppHost examples in tab groups beside the C# and TypeScript ones, and its "Experimental Go AppHost templates" section becomes "Write the AppHost in Go". `go-get-started.mdx` points to the new getting started page. Nothing else links to the old anchor. - **`reference/cli/commands/aspire-new.mdx`, `aspire-add.mdx`, `aspire-restore.mdx` and `aspire-init.mdx`:** the Go templates, `--language go`, and how Go AppHosts are added to and restored. - **`reference/cli/configuration.mdx` and `reference/cli/includes/config-settings-table.md`:** the Go feature flag row is removed from the settings table, and the examples that used it now use the Rust flag, because the Go AppHost doesn't require a flag at GA. Notes for reviewers: - The Go AppHost doesn't require a feature flag at GA (microsoft/aspire#21106), so the pages document none: `go-apphost.mdx` has no flag caution, and the Go row is gone from the CLI configuration reference. The CLI still requires the flag until microsoft/aspire#21183 removes it. - `go-apphost.mdx` shows what `aspire new aspire-go-starter` writes. The `.gitignore` that lists `.aspire/` and the handle checks in the `apphost.go` fence come from microsoft/aspire#21193, so merge this PR after it. - Links to `/reference/api/go/` resolve only once the Go API reference (#1917) is on `release/17.0`, because the link validator skips `/reference/api/**`. - Not in this PR, and tracked as follow-ups: Go tabs on the other pages that have a TypeScript tab and no Go tab (1,030 tab groups in 173 files when audited), Go in the site's AppHost-language pivot, which knows only C# and TypeScript (#1926), and the Java, Python and Rust rows in the CLI configuration reference, which still use the older `experimentalPolyglot:<lang>` colon spelling instead of the flat keys the CLI reads on `main` (#1925). ## Third-party links and affiliations One link: `https://go.dev/dl/`, the official Go download page, in the prerequisites of `go-apphost.mdx`. The author has no material affiliation with the Go project. The loopback URLs in the `aspire.config.json` sample are example values, not links. ## Validation The frontend commands ran in `src/frontend`. | Command | Result | | --- | --- | | `pnpm lint` | exit 0, ESLint `--max-warnings 0` clean, skill digests up to date | | `pnpm test:unit` | exit 0, 84 test files passed, 1169 tests passed, 1 skipped, 0 failed | | `bash tests/scripts/test-forbidden-words.sh` | passed | | `bash .github/scripts/check-forbidden-words.sh 5c48cfb e961e1e` | exit 0, "No forbidden phrases found in added lines." | | `git diff --check upstream/release/17.0...HEAD` | exit 0, no output | | `go build -o NUL ./fences/...` and `go vet ./fences/...` | both exit 0 for the 16 added Go fences and 1 existing one (17 packages, Go 1.27.0), extracted from the page text and built against a real generated SDK | - **Forbidden words:** run locally with an LF-writing `jq`, because the Windows `jq` writes CRLF and made the first local run pass vacuously. CI is the authority. - **Rendering:** all 11 new and edited pages return 200 on a local dev server that includes #1917, with their new content. The 19 distinct internal links and 3 anchors added here resolve, including the Go API reference routes. - **CLI behavior:** `aspire init --language go --non-interactive --suppress-agent-init`, with the Go feature flag set through the environment, exited 0 and wrote `apphost.go`, `go.mod`, `aspire.config.json` and `.aspire/modules`, which is what `aspire-init.mdx` describes. The flag was set because the CLI still requires it until microsoft/aspire#21183 removes it. - **Starter scaffold:** `aspire new aspire-go-starter`, run with a CLI built at the head of microsoft/aspire#21193 and the same feature flag, exited 0 and wrote 8 files. The `apphost.go` fence is byte-identical to the written file after line-ending normalization, the `go.mod` fence matches its `go.mod`, and the file tree and `aspire.config.json` fence show what it wrote, with example port numbers and without two hidden bookkeeping files in `.aspire/modules/`. `go build ./...` and `go vet ./...` passed in the scaffolded project. - **Negative control:** a Go fence that calls a method that doesn't exist fails to compile, so the fence check can fail. - **gofmt:** flags only the existing `main.go` fence in `go-host.mdx` (4-space indentation), which this PR doesn't change. Not run: `pnpm build`, an AppHost end to end, and `aspire add` or `aspire restore` against a Go AppHost. What the `aspire new --language go`, `aspire add` and `aspire restore` references say about Go comes from reading the CLI source. The Go fences compile against an SDK generated before the latest generator changes; they set no handle-typed option fields, so they should be unaffected, but only the starter's `apphost.go` fence was also built against a regenerated SDK, as part of the scaffolded project. The fence build also predates the two commits that remove the Go flag text and the commit that matches the starter's scaffold; none of them changes a Go fence. --------- 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
1 task
David Pine (IEvangelist)
added a commit
to microsoft/aspire
that referenced
this pull request
Oct 29, 2026
> [!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. - [x] No. Follow-up changes expected. - Are you including unit tests for the changes and scenario tests if relevant? - [x] 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 - [x] 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 - [x] No --------- 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
that referenced
this pull request
Oct 30, 2026
> [!NOTE] > **Merge order:** no PR must land before this one. It overlaps #21197, which adds the same `AtsTypeSystemCompatibility.cs` and changes two generator members that this exporter calls. They merge without textual conflicts, but whichever lands second needs a two-line fix-up in `AtsGoCodeGenerator.ApiProjection.cs`, described in #21197. ## Description `aspire sdk export --language go` fails today with "no IApiReferenceExporter", because only TypeScript ships an exporter (#19032). This adds the Go exporter, so the Go API reference can be produced by the same code that generates the Go SDK. aspire.dev builds its Go API reference from `aspire sdk dump` (microsoft/aspire.dev#1917). The Go mode of its `AtsJsonGenerator` re-implements the Go generator's naming and type mapping, so it can drift from what `AtsGoCodeGenerator` really emits, and a dump cannot see the surface the generator writes by hand: - the synthesized `Build()` on the builder - the `InteractionInputCollection` helpers (`Get`, `Required`, `Value`, `RequiredValue`) - `Err()` on every handle and `ToMap()` on options structs - the hand-written `base.go` runtime types - the trailing `opts ...*XxxOptions` flattening and the callback func types The export projects through the generator's own naming and type-mapping code, so aspire.dev can consume `aspire sdk export -l go` for signatures instead of re-deriving them. Part of #21115. ### What changes - **`AtsGoApiReferenceExporter`** (new) implements `IApiReferenceExporter` for Go. It is a separate type from `AtsGoCodeGenerator` on purpose, as in the TypeScript exporter. `Aspire.TypeSystem` is force-shared with a frozen `AssemblyVersion`, so an older CLI binds this assembly but its copy of `Aspire.TypeSystem` has no `IApiReferenceExporter`, and a type that implements the interface cannot load there. `CodeGeneratorResolver` salvages the loadable types, so such a CLI keeps generating Go and only loses the export. - **`AtsGoCodeGenerator`** becomes `partial` (one word in `AtsGoCodeGenerator.cs`). The new `AtsGoCodeGenerator.ApiProjection.cs` builds the export model with the generator's own naming and type-mapping helpers, so there is no second copy of the Go rules to keep in sync. - **`GoDeclarationScanner`** reads the hand-written Go that the generator itself emits (the `base.go` runtime and the builder entry point) instead of keeping a hand-maintained list, so that surface cannot drift either. - **`GoApiModel` and `GoApiExportWriter`** hold the model and write the document. The writer builds a `JsonNode` tree and the exporter returns `JsonDocument.Parse(...).RootElement.Clone()`, the AOT-safe pattern the TypeScript exporter uses (no reflection serializer). Line endings are normalized to LF and items, declarations and members come out in a fixed order, so the output is reproducible byte for byte. - **`src/Shared/CodeGeneration/AtsTypeSystemCompatibility.cs`** (new, linked into the Go project) is the TypeScript generator's version-skew probe in the shared folder. It reads `AtsCapabilityInfo.IsExperimental` reflectively so a newer generator still runs against an older `Aspire.TypeSystem`. The TypeScript project keeps its own copy. - **CLI**: the `--language` help of `aspire sdk export` reads `(e.g., typescript, go)`, and `docs/specs/cli-output-formats.md` describes the Go export next to the TypeScript one. Go resolves through the same language discovery as the other languages, so it needs the existing `experimentalPolyglotGo` feature. - All new types are `internal`, so there is no public API change. About 2,300 lines are product code and 1,700 are tests and snapshots. ### Export shape The envelope matches the TypeScript export so one consumer can read both: `schemaVersion` (1), `language` (`go`), `generator` (`name`, `version`), `package` (`name`, `version`, and Go's `importPath`), `modules[]` (`name`, `items[]`) and `declarations[]` (`id`, `owningAssembly`, `content`). - `items[].kind` is `interface`, `augmentation` (members a package adds to a type that another package declares), `dto`, `options`, `enum`, `variable`, `function` or `type`. - `members[].kind` is `method`, `field` or `constant`. Every member has the exact Go text in `declaration`. Capability-backed members carry `capabilityId`, and members that the generator writes itself are marked `synthesized`. Methods also carry `errorModel` (`none`, `returned` or `deferred`), `experimental` and `deprecated` markers where they apply, and an `options` block (the struct type and its fields) when the method takes the trailing `opts ...*XxxOptions`. Trimmed excerpt of the Redis export. `AddRedis` shows the trailing options flattening and `ToMap()` shows a synthesized member: ```json { "id": "DistributedApplicationBuilder.AddRedis", "kind": "method", "name": "AddRedis", "declaration": "AddRedis(name string, options ...*AddRedisOptions) RedisResource", "capabilityId": "Aspire.Hosting.Redis/addRedis", "returnType": "RedisResource", "errorModel": "deferred", "parameters": [ { "name": "name", "type": "string", "optional": false } ], "options": { "typeName": "AddRedisOptions", "fields": [ { "name": "Port", "type": "*float64", "optional": true, "jsonName": "port" }, { "name": "Password", "type": "*ParameterResource", "optional": true, "jsonName": "password" } ] } } ``` ```json { "id": "AddRedisOptions.ToMap", "kind": "method", "name": "ToMap", "declaration": "ToMap() map[string]any", "returnType": "map[string]any", "errorModel": "none", "synthesized": true } ``` ### Sample exports Produced end to end with a Debug-built CLI from this checkout. The integration packages restore from NuGet, while `Aspire.Hosting` and the Go generator are this checkout's. | Export | Items | Members | Synthesized members | Size | | --- | ---: | ---: | ---: | ---: | | `Aspire.Hosting.Redis@13.6.1` | 12 | 48 | 10 (`Err()` x3, `ToMap()` x7) | 37,045 B | | `Aspire.Hosting.Azure.Storage@13.6.1` | 30 | 81 | 16 | 63,536 B | | `Aspire.Hosting` (core) | 260 | 1,609 | 250 | 1,148,073 B | The core export flags 170 experimental and 10 deprecated members. Repeating an export in a new process gives byte-identical output (SHA-256 compared). Exit codes and timings are in the Validation section. ### Compared with the dump-derived reference (owner, method) pairs that exist both in the export and in aspire.dev's current `go-modules` data (13.6.0), compared by exact Go signature: | Package | Pairs in both | Identical | | --- | ---: | ---: | | `Aspire.Hosting.Redis` | 22 | 22 | | `Aspire.Hosting.Azure.Storage` | 36 | 15 | | `Aspire.Hosting` (core) | 863 | 420 | Every non-identical pair is a return-type difference (the dump-derived reference declares the capability's declared type, such as `Resource`, or drops a nullable pointer, where the generator returns the receiver's own interface or `*string`), and the export reports what the generator emits. The core export is this checkout's build, so its 41 export-only pairs are capabilities newer than 13.6.0, not drift. ### Merging with the godoc PR This change applies to `main` on its own and is independent of the godoc PR ("Emit godoc from ATS documentation metadata in the Go SDK generator"). Both change `AtsGoCodeGenerator.cs` in different places, and both add `src/Shared/CodeGeneration/AtsTypeSystemCompatibility.cs` with identical content plus the same link line in the Go project (the godoc PR also points the TypeScript generator at that shared file), so git merges them without conflicts. The PR that merges second needs a two-line fix-up that git cannot detect, because the godoc change adds `BuildDocumentationMaps` and an `includeDocs` parameter to `RenderGoExportedValueType`: 1. In `AtsGoCodeGenerator.ApiProjection.cs`, `BuildApiModel`: add `BuildDocumentationMaps(context);` directly after `BuildNameMaps(context);`, so documentation rendering during the projection has its maps. 2. In `ProjectExportedValues`: call `RenderGoExportedValueType(node, indentLevel: 0, includeDocs: false)`, because the call no longer compiles without the new argument. Then re-accept `GoApiExportTests.GoOnlySurface.verified.json`: DTO, enum and field summaries now flow into the export. With both changes merged and the fix-up applied, the Go codegen test project passes. ### Behavior notes - Documentation text is whatever the generator emits today. In the SDK-built AppHost server that the Debug CLI used, a restored integration's XML documentation file was not next to its assembly, so summaries are sparse for those NuGet integrations (Redis 11 of 48 members, Azure Storage 9 of 81) and fuller for `Aspire.Hosting`, a project reference (1,068 of 1,609). - The scanner reads the layout of the generator's own output. The parity tests fail if that layout changes in a way the scanner cannot read. - Names are reserved across all types in the context (the exported package plus `Aspire.Hosting`), as in generation. An app that combines many integrations can get a different disambiguation suffix where two packages collide. - The export is a pure function of the ATS context: no new process launches, file IO or network calls. The core export is about 1.1 MB. - The CLI writes the document to stdout followed by a platform newline. ### Tests - `GoApiExportTests` (28 cases, three Verify snapshots) projects a test AppHost through the real generator and checks parity in both directions: every type, function, interface member and variable the generator emits is in the export, and nothing is exported that the generator does not emit. It also covers the Go-only members, trailing options flattening, callbacks and unions, augmenting packages, unique ids, determinism, LF line endings, cancellation and the scanner. - `ApiReferenceExportTests` and `CodeGenerationResolverTests` (RemoteHost) resolve and run the Go exporter through `CodeGenerationService`. The existing "language without an exporter" test uses Python instead of Go, since Go ships an exporter. - `SdkExportCommandTests` (CLI) checks that `sdk export --language go` resolves the Go generator when the feature is enabled. ### Follow-ups 1. Go export: add `type` and `optional` to DTO fields and constants (from `AtsDtoPropertyInfo.IsOptional`). Today the type is only inside the member `declaration`, and every DTO field carries `omitempty`. 2. aspire.dev: build the Go API reference from `aspire sdk export -l go`, which removes the return-type and nullable differences above. 3. Copy XML documentation next to restored integration assemblies in the SDK-built AppHost, so NuGet integrations get summaries. 4. Go export: optional grouped `functions` and `appliesTo` view. The dump-derived reference lists one signature per capability, while the export repeats a member per concrete interface. ## Validation | Command | Exit | Result | | --- | --- | --- | | `.\restore.cmd` | 0 | passed | | `dotnet test --project tests/Aspire.Hosting.CodeGeneration.Go.Tests/Aspire.Hosting.CodeGeneration.Go.Tests.csproj --no-launch-profile -- --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"` | 0 | 61 total, 61 passed, 0 failed, 0 skipped (28 are new) | | `dotnet test --project tests/Aspire.Hosting.RemoteHost.Tests/Aspire.Hosting.RemoteHost.Tests.csproj --no-launch-profile -- --filter-class "*.ApiReferenceExportTests" --filter-class "*.CodeGenerationResolverTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"` | 0 | 21 total, 21 passed, 0 failed, 0 skipped | | `dotnet test --project tests/Aspire.Cli.Tests/Aspire.Cli.Tests.csproj --no-launch-profile -- --filter-class "*.SdkExportCommandTests" --filter-not-trait "quarantined=true" --filter-not-trait "outerloop=true"` | 0 | 31 total, 31 passed, 0 failed, 0 skipped | | `dotnet run --project tools/SelectTests -- --from upstream/main --to HEAD --explain` | 0 | 16 changed files, 0 unattributed, 4 of 99 test projects selected | | `aspire sdk export --language go --package Aspire.Hosting.Redis@13.6.1` | 0 | 37,045 B in 21.3 s (includes building the AppHost server) | | `aspire sdk export --language go --package Aspire.Hosting.Azure.Storage@13.6.1` | 0 | 63,536 B in 8.0 s | | `aspire sdk export --language go` | 0 | 1,148,073 B in 7.8 s | `upstream` is the microsoft/aspire remote. The three exports ran in a directory whose `aspire.config.json` contains `{"features":{"experimentalPolyglotGo":true}}`, with `DOTNET_ROOT` pointing at this checkout's `.dotnet` and `ASPIRE_CLI_TELEMETRY_OPTOUT=1`. Stdout is the JSON document only. Times are wall clock on a developer machine. The new Verify snapshots (`GoApiExportTests.FocusedApiExport`, `GoOnlySurface` and `AugmentingPackage`) were reviewed before they were accepted. Conditional test selection: the selector selects `Aspire.Cli.EndToEnd.Tests`, `Aspire.Cli.Tests`, `Aspire.Hosting.CodeGeneration.Go.Tests` and `Aspire.Hosting.RemoteHost.Tests` and triggers `cli-starter-validation`, `extension-e2e`, `polyglot` and `typescript-api-compat`. The new files live in projects the trigger map already covers, and the linked shared file is attributed by the project graph, so `eng/github-ci/test-trigger-map.yml` needs no change. Not verified: - The full `Aspire.Cli.Tests` and `Aspire.Hosting.RemoteHost.Tests` suites. Only the classes above ran. The TypeScript exporter and the other languages' generators are not touched and were not run. - A release or native AOT build of the CLI. The exports above use a Debug CLI, and the only CLI change is a help string. - `aspire sdk export --language go` with `experimentalPolyglotGo` off was not run. Reading the code, language discovery does not list Go in that case (`DefaultLanguageDiscovery`), so the CLI does not add the Go generator package and the AppHost server answers `No code generator found for language: go. Available languages: ...`, which does not name the feature. The other experimental languages behave the same way, and the message goes away when the feature flag is removed (#21106). - The bundle (prebuilt AppHost) flow and integrations referenced as local projects. Summary coverage there is not measured. - Apps that combine many integrations. Names are compared only for the exported package plus `Aspire.Hosting`. - The polyglot validation job and the rest of the CI matrix. CI is the first run there. - The combination with the godoc PR beyond the Go codegen test project, which passed on a throwaway merge. No end-to-end export was run on the merged tree. ## Checklist - Is this feature complete? - [ ] Yes. Ready to ship. - [x] No. Follow-up changes expected. - Are you including unit tests for the changes and scenario tests if relevant? - [x] 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 - [x] 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 - [x] No --------- 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
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.

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 onrelease/17.0.Summary
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 apiparses from the sitemap.What changes:
AtsJsonGeneratorgains a Go mode (--language go). It ports the Go SDK generator's naming and type rules (PascalCase,(T, error)results, trailingopts ...*XxxOptions, pointers,*List[T],*Dict[K,V]) and reads the sameaspire sdk dumpJSON as the TypeScript mode.generate-ts-api-json.ps1takes-Language typescript|go.pnpm update:go-api,update-integration-data.ps1and the normalizer handle Go data.update-integration-data.ymlstagessrc/frontend/src/data/go-modulesand its timeout goes from 45 to 75 minutes, since the job now runs C#, TypeScript and Go passes.src/frontend/src/data/go-modules/(5.75 MB), generated from the same package versions asts-modules.go-*utilities, aGoMemberCardcomponent andreference/api/go/**routes, plus registrations in the reference sidebar, search, overview and dev hub. The dev hub gets aGo APIreference link, so the item count assertion indev-layout.spec.tsgoes from 30 to 31.GoDocTextcomponent. 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.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 infilter-navigation.spec.ts: the existing test already uses 48 to 75 s of its 120 s budget onrelease/17.0CI, so a fourth iteration would leave little margin.Design notes:
Aspire.Hosting.Redis), as in TypeScript. The Go SDK itself is one flat package, so each module page states the import path.main.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 onrelease/17.0. The baseAspire.Hosting.Azure.Provisioningpackage is included.Not in this PR:
<ApiReference>Go links and a Go option in the AppHost language switcher. The switcher is hard-wired tocsharp|typescriptand needs Go docs tabs first ([Go AppHost preview] Documentation and sample conversion aspire#21112).go-modulesinmerge-main-into-release.shgenerated_dirsand its test. Add it after the post-GA swap, whenmainhas Go data.func(...any) any, and foreign enums and hand-written SDK types have no pages. A GoIApiReferenceExporter(aspire sdk export --language go) would replace the dump-derived signatures.Notes:
--base main, so refreshing 17.0 data needs a manual run and arelease/17.0base.mainfail atgenerate-package-json.ps1:112($_.apiReferenceunder StrictMode). That is unrelated and untouched here.Third-party links and affiliations
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-modulesdata: 13 distinct hosts, every one already present there.Validation
The frontend commands run in
src/frontendwithCI=1. The unit, lint and markdown crawl results below are for the final head. The localpnpm buildand Playwright results are fromd7d7633e41, before the doc text and sidebar casing commits. CI on the final heade506f71a33passed 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..mdroute 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 200text/markdownwith no{@markers left and no unbalanced backticks, and the crawled set equals whatgetStaticPathsgenerates.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=0on the Go specs and the specs extended for Go: 125 passed, 1 skipped.dev-layout.spec.tshub item count failed in all three and was a real regression from the newGo APIlink; it is fixed in this PR. The other 9 failures were timeouts under that load (dev-browse,filter-navigation,gallery-search-contractand one mobiledev-layouttest). Every failing test passed when rerun alone with--workers=1 --retries=0, andfilter-navigation.spec.tspasses in full on all three projects after the version-dropdown split.generate-ts-api-json.ps1 -Language goand the normalizer matched the checked-in data with 0 diffs. After the Foundry fix below,Aspire.HostingandAspire.Hosting.Foundrywere regenerated again: core is byte-identical and Foundry matches the committed file.aspire docs api list|search|getagainst a local build of this site, using the CLI from Add Go support to aspire docs api aspire#21173:list goreturns 122 modules,search "redis password" --language goranksgo/aspire.hosting.redis/redisresource/withpasswordfirst, and C# and TypeScript output is identical to the previous CLI.Aspire.Hosting.Foundry(201FoundryModels.*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.