Add aspire docs api * sub-commands to expose aspire.dev reference material#15814
Open
IEvangelist wants to merge 23 commits intomainfrom
Open
Add aspire docs api * sub-commands to expose aspire.dev reference material#15814IEvangelist wants to merge 23 commits intomainfrom
aspire docs api * sub-commands to expose aspire.dev reference material#15814IEvangelist wants to merge 23 commits intomainfrom
Conversation
Contributor
|
🚀 Dogfood this PR with:
curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 15814Or
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 15814" |
IEvangelist
force-pushed
the
dapine/aspire-api-docs-commands
branch
from
15ed66f to
5fa4582
Compare
- Added Turkish, Simplified Chinese, and Traditional Chinese translations for API command strings. - Implemented TerminalMarkdownFormatter for formatting markdown content in terminal output. - Created comprehensive tests for API commands, including help display, listing entries, and searching with filters. - Developed ApiDocsIndexService tests to validate API documentation indexing and retrieval. - Introduced ApiSitemapParser tests to ensure correct parsing of API sitemap structures. - Added TestApiDocsFetcher for testing purposes, providing a mock implementation of IApiDocsFetcher.
IEvangelist
force-pushed
the
dapine/aspire-api-docs-commands
branch
from
9aad93b to
b3a9869
Compare
IEvangelist
force-pushed
the
dapine/aspire-api-docs-commands
branch
from
06a9cee to
6d218ba
Compare
IEvangelist
requested review from
JamesNK,
davidfowl and
mitchdenny
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new aspire api command group (list/search/get) backed by an indexed aspire.dev API sitemap, refactors docs caching/indexing into a shared documentation infrastructure, and introduces new resource strings plus localization artifacts.
Changes:
- Implement
aspire apicommands and an API docs indexing pipeline (sitemap parsing, caching, search/list/get). - Refactor docs fetching/caching to a shared
Documentationlayer (fingerprinting, file-backed cache, lexical scoring, terminal markdown formatting). - Add/adjust CLI tests and agent skill docs to cover and document the new API commands.
Reviewed changes
Copilot reviewed 69 out of 70 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/Aspire.Cli.Tests/Utils/CliTestHelper.cs | Registers API docs services/commands in test DI container. |
| tests/Aspire.Cli.Tests/TestServices/TestDocsFetcher.cs | Updates test fetcher namespace after docs refactor. |
| tests/Aspire.Cli.Tests/TestServices/TestApiDocsFetcher.cs | Adds a minimal test double for IApiDocsFetcher. |
| tests/Aspire.Cli.Tests/Mcp/TestDocsIndexService.cs | Updates test index service namespace after docs refactor. |
| tests/Aspire.Cli.Tests/Mcp/Docs/LlmsTxtParserTests.cs | Moves tests to the new Documentation.Docs namespace. |
| tests/Aspire.Cli.Tests/Mcp/Docs/DocsSearchServiceTests.cs | Updates namespace and adapts to new cache fingerprint API. |
| tests/Aspire.Cli.Tests/Mcp/Docs/DocsIndexServiceTests.cs | Adds tests for cached-index rebuild and offline-cache fallback behavior. |
| tests/Aspire.Cli.Tests/Mcp/Docs/DocsFetcherTests.cs | Updates fetcher construction to include configuration; adapts cache interface. |
| tests/Aspire.Cli.Tests/Mcp/ApiDocs/ApiSitemapParserTests.cs | Adds coverage for sitemap filtering and segment parsing rules. |
| tests/Aspire.Cli.Tests/Mcp/ApiDocs/ApiDocsSourceConfigurationTests.cs | Adds coverage for cache keys and host rebasing behavior. |
| tests/Aspire.Cli.Tests/Mcp/ApiDocs/ApiDocsIndexServiceTests.cs | Adds coverage for API index hierarchy, search, get, rebasing, and cache rebuild. |
| tests/Aspire.Cli.Tests/Commands/DocsCommandTests.cs | Updates tests to new docs namespace. |
| tests/Aspire.Cli.Tests/Commands/ApiCommandTests.cs | Adds end-to-end CLI tests for aspire api behaviors. |
| src/Aspire.Cli/Utils/TerminalMarkdownFormatter.cs | Centralizes terminal-friendly markdown formatting. |
| src/Aspire.Cli/Resources/xlf/ApiCommandStrings.zh-Hant.xlf | Adds Traditional Chinese XLF file for API command strings. |
| src/Aspire.Cli/Resources/xlf/ApiCommandStrings.zh-Hans.xlf | Adds Simplified Chinese XLF file for API command strings. |
| src/Aspire.Cli/Resources/xlf/ApiCommandStrings.tr.xlf | Adds Turkish XLF file for API command strings. |
| src/Aspire.Cli/Resources/xlf/ApiCommandStrings.ru.xlf | Adds Russian XLF file for API command strings. |
| src/Aspire.Cli/Resources/xlf/ApiCommandStrings.pt-BR.xlf | Adds Portuguese (Brazil) XLF file for API command strings. |
| src/Aspire.Cli/Resources/xlf/ApiCommandStrings.pl.xlf | Adds Polish XLF file for API command strings. |
| src/Aspire.Cli/Resources/xlf/ApiCommandStrings.ko.xlf | Adds Korean XLF file for API command strings. |
| src/Aspire.Cli/Resources/xlf/ApiCommandStrings.ja.xlf | Adds Japanese XLF file for API command strings. |
| src/Aspire.Cli/Resources/xlf/ApiCommandStrings.it.xlf | Adds Italian XLF file for API command strings. |
| src/Aspire.Cli/Resources/xlf/ApiCommandStrings.fr.xlf | Adds French XLF file for API command strings. |
| src/Aspire.Cli/Resources/xlf/ApiCommandStrings.es.xlf | Adds Spanish XLF file for API command strings. |
| src/Aspire.Cli/Resources/xlf/ApiCommandStrings.de.xlf | Adds German XLF file for API command strings. |
| src/Aspire.Cli/Resources/xlf/ApiCommandStrings.cs.xlf | Adds Czech XLF file for API command strings. |
| src/Aspire.Cli/Resources/ApiCommandStrings.resx | Adds API command string resources. |
| src/Aspire.Cli/Resources/ApiCommandStrings.Designer.cs | Adds generated strongly-typed accessor for API command strings. |
| src/Aspire.Cli/README.md | Documents the new api command and provides example usage. |
| src/Aspire.Cli/Program.cs | Wires API docs services + commands into the CLI host. |
| src/Aspire.Cli/Mcp/Tools/SearchDocsTool.cs | Updates docs tool to new docs namespace. |
| src/Aspire.Cli/Mcp/Tools/ListDocsTool.cs | Updates docs tool to new docs namespace. |
| src/Aspire.Cli/Mcp/Tools/GetDocTool.cs | Updates docs tool to new docs namespace. |
| src/Aspire.Cli/Mcp/Tools/DocsToolHelper.cs | Updates docs tool helper to new docs namespace. |
| src/Aspire.Cli/Mcp/Docs/DocsFetcher.cs | Removes old MCP docs fetcher (moved/refactored). |
| src/Aspire.Cli/Mcp/Docs/DocsCache.cs | Removes old MCP docs cache (moved/refactored). |
| src/Aspire.Cli/JsonSourceGenerationContext.cs | Adds JSON source-gen metadata for API docs models and new namespaces. |
| src/Aspire.Cli/Documentation/SourceContentFingerprint.cs | Adds stable fingerprinting for cached source content changes. |
| src/Aspire.Cli/Documentation/LexicalScoring.cs | Extracts shared tokenization and scoring helpers. |
| src/Aspire.Cli/Documentation/IDocumentContentCache.cs | Refactors base cache interface into shared documentation namespace. |
| src/Aspire.Cli/Documentation/FileBackedDocumentContentCache.cs | Introduces shared file-backed cache for text/ETag/JSON payloads. |
| src/Aspire.Cli/Documentation/Docs/LlmsTxtParser.cs | Moves parser into new docs namespace. |
| src/Aspire.Cli/Documentation/Docs/IDocsCache.cs | Adds docs cache interface including index fingerprint support. |
| src/Aspire.Cli/Documentation/Docs/DocsSourceConfiguration.cs | Adds config for overriding llms.txt source and cache key derivation. |
| src/Aspire.Cli/Documentation/Docs/DocsSearchService.cs | Moves docs search service into new docs namespace. |
| src/Aspire.Cli/Documentation/Docs/DocsIndexService.cs | Adds fingerprint-based cache rebuild and shared lexical scoring usage. |
| src/Aspire.Cli/Documentation/Docs/DocsFetcher.cs | Adds configurable docs fetcher using shared cached HTTP fetch helper. |
| src/Aspire.Cli/Documentation/Docs/DocsCache.cs | Implements docs cache using the shared file-backed cache. |
| src/Aspire.Cli/Documentation/CachedHttpDocumentFetcher.cs | Adds shared ETag-aware HTTP fetch + cache fallback behavior. |
| src/Aspire.Cli/Documentation/ApiDocs/IApiDocsCache.cs | Defines cache interface for API docs including index fingerprint support. |
| src/Aspire.Cli/Documentation/ApiDocs/ApiSitemapParser.cs | Implements sitemap parsing and route extraction for modeled languages. |
| src/Aspire.Cli/Documentation/ApiDocs/ApiDocsSourceConfiguration.cs | Adds config for sitemap URL override and host rebasing/markdown URL rules. |
| src/Aspire.Cli/Documentation/ApiDocs/ApiDocsIndexService.cs | Implements API index build/list/search/get models and scoring. |
| src/Aspire.Cli/Documentation/ApiDocs/ApiDocsFetcher.cs | Implements API sitemap/page fetcher using shared cached HTTP helper. |
| src/Aspire.Cli/Documentation/ApiDocs/ApiDocsCache.cs | Implements API docs cache using shared file-backed cache. |
| src/Aspire.Cli/Commands/RootCommand.cs | Adds api to the root command subcommands. |
| src/Aspire.Cli/Commands/DocsSearchCommand.cs | Updates docs command to new docs namespace. |
| src/Aspire.Cli/Commands/DocsListCommand.cs | Updates docs command to new docs namespace. |
| src/Aspire.Cli/Commands/DocsGetCommand.cs | Uses shared TerminalMarkdownFormatter and new docs namespace. |
| src/Aspire.Cli/Commands/ApiSearchCommand.cs | Adds aspire api search command implementation. |
| src/Aspire.Cli/Commands/ApiListCommand.cs | Adds aspire api list command implementation. |
| src/Aspire.Cli/Commands/ApiGetCommand.cs | Adds aspire api get command implementation. |
| src/Aspire.Cli/Commands/ApiCommand.cs | Adds aspire api parent command wiring list/search/get. |
| src/Aspire.Cli/Commands/AgentMcpCommand.cs | Updates docs dependency to new docs namespace. |
| docs/specs/api-docs-commands.md | Adds a spec describing the new API docs command surface and behavior. |
| .agents/skills/aspire/SKILL.md | Updates agent guidance to use aspire api for reference lookups. |
| .agents/skills/aspire/references/tools-and-configuration.md | Documents aspire api alongside aspire docs for workflows. |
| .agents/skills/aspire/references/csharp-apphosts.md | Adds API-reference lookup guidance for C# AppHost work. |
| .agents/skills/aspire/references/agent-workflows.md | Updates workflows to include API reference commands. |
Files not reviewed (1)
- src/Aspire.Cli/Resources/ApiCommandStrings.Designer.cs: Language not supported
JamesNK
reviewed
Apr 9, 2026
JamesNK
reviewed
Apr 9, 2026
JamesNK
reviewed
Apr 9, 2026
Member
JamesNK
left a comment
JamesNK
left a comment
There was a problem hiding this comment.
2 issues flagged: 1 bug (cancellation swallowed in shared HTTP fetcher), 1 behavioral change (docs index now requires network on every cold start).
IEvangelist
changed the title
aspire api * commands to expose aspire.dev reference material
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
IEvangelist
changed the title
aspire api * commands to expose aspire.dev reference materialaspire docs api * sub-commands to expose aspire.dev reference material
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Parse C# type markdown overview links into a lazily-built cached member index so api search and anchored get can resolve member-level results like WithCommand without crawling every member-group page. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Load the grouped-member index when base route hits still need member results, and build member items from member-group parents discovered from routes instead of C#-specific member-index assumptions. Add WithEnv and generic parser regressions for grouped member links. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Stop building the grouped-member cache for the entire API corpus on the first search. Member containers are now loaded and persisted only as search, list, and get touch them, with batched search expansion instead of a full eager crawl. Also rewrite site-relative API markdown links to configured-host absolute URLs so returned markdown is clickable. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- shorten synthetic member ids for readability while keeping overloads distinct - improve broad prefix ranking so coarse queries prefer closer type hits - fix markdown link rewriting for bracketed signatures in returned API markdown Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- handle bracketed link text in the Spectre markdown converter used by docs api get - add exact distributedapplication regressions for link rewriting and displayed output Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- read llms.txt and API sitemap overrides from aspire config paths - model and migrate the docs settings in local/global config files - add config command, schema, and source configuration regressions Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
10 tasks
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
|
🎬 CLI E2E Test Recordings — 58 recordings uploaded (commit View recordings
📹 Recordings uploaded automatically from CI run #24260910289 |
davidfowl
reviewed
Apr 11, 2026
Comment on lines
+49
to
+52
| aspire docs api list java | ||
| aspire docs api list go | ||
| aspire docs api list rust | ||
| aspire docs api list python |
Contributor
There was a problem hiding this comment.
does this work, lets remove this for now.
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.
Summary
aspire docs api list|search|getto browse Aspire API reference material fromaspire.devhttps://aspire.dev/sitemap-0.xmland fetch API page markdown directly from the matching reference pagesaspire docs listrows from extra landing-page H1 contentDetails
aspire docs api ...rather than a top-levelaspire api ...java,go,python, andrustgetreturns markdown and renders it through the shared interaction-service markdown rendererAspire.Cli.Documentation, with prose docs inDocumentation.Docsand API docs inDocumentation.ApiDocsCachedHttpDocumentFetcherDocsIndexServicellms-small.txtandllms-small.etag.txtLlmsTxtParserfrom splitting landing-page hero H1 content into bogus extra documentsTesting
docs api list|search|getFixes #14911
Fixes #14346
Fixes #15840
Dependencies
None
Checklist
<remarks />and<code />elements on your triple slash comments?aspire.devissue: