dotnet-api-docs

API documentation generation for .NET projects: DocFX setup for API reference from assemblies (docfx.json configuration, metadata extraction, template customization, cross-referencing), OpenAPI spec as living API documentation (Scalar and Swagger UI embedding, versioned OpenAPI documents), documentation-code synchronization (CI validation with -warnaserror:CS1591 , broken link detection, automated doc builds on PR), API changelog patterns (breaking change documentation, migration guides, deprecated API tracking), and versioned API documentation (version selectors, multi-version maintenance, URL patterns).

Version assumptions: DocFX v2.x (community-maintained). OpenAPI 3.x via Microsoft.AspNetCore.OpenApi (.NET 9+ built-in). Scalar UI for modern OpenAPI visualization. .NET 8.0+ baseline for code examples.

Scope

• DocFX setup for API reference (metadata extraction, template customization, cross-referencing)

• OpenAPI spec as living documentation (Scalar and Swagger UI embedding)

• Documentation-code synchronization (CI validation, broken link detection)

• API changelog patterns (breaking changes, migration guides, deprecated API tracking)

• Versioned API documentation (version selectors, multi-version maintenance)

Out of scope

• XML documentation comment syntax and authoring -- see [skill:dotnet-xml-docs]

• OpenAPI spec generation and configuration -- see [skill:dotnet-openapi]

• CI/CD deployment pipelines for documentation sites -- see [skill:dotnet-gha-deploy]

• Documentation platform selection and initial setup -- see [skill:dotnet-documentation-strategy]

• Changelog generation tooling and SemVer versioning -- see [skill:dotnet-release-management]

Cross-references: [skill:dotnet-xml-docs] for XML doc comment authoring, [skill:dotnet-openapi] for OpenAPI generation, [skill:dotnet-gha-deploy] for doc site deployment pipelines, [skill:dotnet-documentation-strategy] for platform selection, [skill:dotnet-release-management] for changelog tooling and versioning.

DocFX Setup for .NET API Reference

DocFX generates API reference documentation directly from .NET assemblies and XML documentation comments. It is the only documentation tool with native docfx metadata extraction from .NET projects.

Installation

Install DocFX as a .NET global tool

dotnet tool install -g docfx

Or as a local tool (recommended for team consistency)

dotnet new tool-manifest dotnet tool install docfx

Configuration (docfx.json )

{ "metadata": [ { "src": [ { "files": ["src//*.csproj"], "exclude": ["/bin/", "/obj/"], "src": ".." } ], "dest": "api", "properties": { "TargetFramework": "net8.0" }, "disableGitFeatures": false, "disableDefaultFilter": false } ], "build": { "content": [ { "files": ["api/.yml", "api/index.md"] }, { "files": [ "articles/.md", "articles//toc.yml", "toc.yml", "*.md" ] } ], "resource": [ { "files": ["images/**"] } ], "dest": "_site", "globalMetadataFiles": [], "fileMetadataFiles": [], "template": ["default", "modern"], "postProcessors": ["ExtractSearchIndex"], "markdownEngineName": "markdig", "noLangKeyword": false, "keepFileLink": false, "cleanupCacheHistory": false, "disableGitFeatures": false, "globalMetadata": { "_appTitle": "My.Library API Reference", "_appFooter": "Copyright 2024 My Company", "_enableSearch": true, "_enableNewTab": true } } }

Metadata Extraction

The metadata section controls how DocFX extracts API information from .NET projects:

Generate API metadata YAML files from projects

docfx metadata docfx.json

This creates YAML files in the api/ directory:

api/MyLibrary.WidgetService.yml

api/MyLibrary.Widget.yml

api/toc.yml

Key metadata configuration options:

Property Purpose Default

src.files

Project files to extract from Required

dest

Output directory for YAML api

properties.TargetFramework

TFM to build against Project default

disableGitFeatures

Skip git blame info false

filter

Path to API filter YAML None (all public APIs)

API Filtering

Exclude internal types from the generated documentation:

filterConfig.yml

apiRules:

• exclude: uidRegex: ^MyLibrary.Internal. type: Namespace
• exclude: hasAttribute: uid: System.ComponentModel.EditorBrowsableAttribute ctorArguments: - System.ComponentModel.EditorBrowsableState.Never

Reference the filter in docfx.json :

{ "metadata": [ { "filter": "filterConfig.yml" } ] }

Template Customization

DocFX supports template overrides for custom branding:

docs/ templates/ custom/ styles/ main.css # Custom CSS overrides partials/ head.tmpl.partial # Custom head section (analytics, fonts) footer.tmpl.partial

Reference custom templates in docfx.json :

{ "build": { "template": ["default", "modern", "templates/custom"] } }

Cross-Referencing Between Pages

DocFX supports uid -based cross-references between API pages and conceptual articles:

<!-- In a conceptual article --> See the @MyLibrary.WidgetService.CreateWidgetAsync(System.String) method for details.

For the full API, see <xref:MyLibrary.WidgetService>.

In an API YAML override file (api/MyLibrary.WidgetService.yml)

Add links to conceptual articles

references:

• uid: MyLibrary.WidgetService seealso:
  • linkId: ../articles/getting-started.md commentId: getting-started

OpenAPI Spec as Documentation

Generated OpenAPI specifications serve as living API documentation that stays in sync with the code. This section covers using OpenAPI output as documentation; for OpenAPI generation and configuration, see [skill:dotnet-openapi].

Scalar UI Embedding

Scalar provides a modern, interactive API documentation viewer:

// Program.cs var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment()) { app.MapOpenApi(); // Serves OpenAPI JSON at /openapi/v1.json app.MapScalarApiReference(options => { options.WithTitle("My API Documentation") .WithTheme(ScalarTheme.Purple) .WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient); }); }

app.Run();

Scalar renders the OpenAPI spec as an interactive documentation page with:

• Endpoint grouping by tags

• Request/response examples

• Authentication configuration

• "Try it" functionality for testing endpoints

Swagger UI Embedding

For projects using Swashbuckle or requiring the classic Swagger UI:

if (app.Environment.IsDevelopment()) { app.UseSwaggerUI(options => { options.SwaggerEndpoint("/openapi/v1.json", "My API v1"); options.RoutePrefix = "api-docs"; options.DocumentTitle = "My API Documentation"; options.DefaultModelsExpandDepth(-1); // Hide schemas by default }); }

Versioned OpenAPI Documents

Serve multiple OpenAPI documents for different API versions:

builder.Services.AddOpenApi("v1", options => { options.AddDocumentTransformer((document, context, ct) => { document.Info.Version = "1.0"; document.Info.Title = "My API"; return Task.CompletedTask; }); });

builder.Services.AddOpenApi("v2", options => { options.AddDocumentTransformer((document, context, ct) => { document.Info.Version = "2.0"; document.Info.Title = "My API"; return Task.CompletedTask; }); });

// Serves /openapi/v1.json and /openapi/v2.json app.MapOpenApi();

Exporting OpenAPI for Static Documentation

Export the OpenAPI spec at build time for use in static documentation sites:

Generate OpenAPI spec from the running application

dotnet run -- --urls "http://localhost:5099" & APP_PID=$! sleep 3 curl -s http://localhost:5099/openapi/v1.json > docs/openapi/v1.json kill $APP_PID

Alternatively, use the Microsoft.Extensions.ApiDescription.Server package to generate at build time:

<PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="8.0.0"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>

<PropertyGroup> <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments> <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)/../docs/openapi</OpenApiDocumentsDirectory> </PropertyGroup>

For OpenAPI generation setup and Swashbuckle migration details, see [skill:dotnet-openapi].

Doc Site Generation from XML Comments

XML Docs to DocFX (Static HTML)

The primary pipeline for library API reference documentation:

Source Code (.cs files) | v XML Doc Comments (/// <summary>...) | v Build with GenerateDocumentationFile=true | v XML Doc File (MyLibrary.xml) | v docfx metadata (extracts API structure) | v YAML Files (api/*.yml) | v docfx build (generates HTML) | v Static HTML Site (_site/)

For XML documentation comment authoring best practices, see [skill:dotnet-xml-docs].

XML Docs to Starlight (via Markdown Extraction)

For projects using Starlight instead of DocFX, extract API documentation as Markdown:

• Generate the XML doc file with <GenerateDocumentationFile>true</GenerateDocumentationFile>

• Use a conversion tool to transform XML docs to Markdown pages:

• xmldoc2md (community tool): converts XML doc files to Markdown

• Custom script: parse the XML file and generate Markdown pages for each type

Using xmldoc2md

dotnet tool install -g XMLDoc2Markdown xmldoc2md MyLibrary.dll docs/src/content/docs/reference/

Output: one Markdown file per type in the reference/ directory

• Include in Starlight build:

docs/src/content/docs/ reference/ MyLibrary.WidgetService.md # Auto-generated from XML docs MyLibrary.Widget.md MyLibrary.WidgetStatus.md

Configure the sidebar to auto-generate from the reference directory:

// astro.config.mjs sidebar: [ { label: 'API Reference', autogenerate: { directory: 'reference' }, }, ],

Keeping Docs in Sync with Code

CI Validation of Doc Completeness

Enforce XML documentation completeness in CI by treating CS1591 as an error:

<!-- Directory.Build.props --> <PropertyGroup> <GenerateDocumentationFile>true</GenerateDocumentationFile> </PropertyGroup>

<!-- For public library projects only --> <PropertyGroup Condition="'$(IsPublicLibrary)' == 'true'"> <WarningsAsErrors>$(WarningsAsErrors);CS1591</WarningsAsErrors> </PropertyGroup>

CI command: build with warnings-as-errors for doc completeness

dotnet build -warnaserror:CS1591

This fails the build if any public member is missing XML documentation. Use the IsPublicLibrary condition (or per-project configuration) to apply only to published NuGet packages, not test projects or internal tools.

Broken Link Detection

Validate documentation links in CI:

Build DocFX and check for broken cross-references

docfx build docfx.json --warningsAsErrors

DocFX reports broken xref links as warnings -- the flag promotes them to errors

For Starlight or Docusaurus sites, use a link checker after building:

Build the doc site

npm run build

Check for broken links in the built output

npx broken-link-checker-local ./_site --recursive

Automated Doc Builds on PR

Validate documentation builds on every pull request without deploying. For the deployment workflow configuration, see [skill:dotnet-gha-deploy]. The validation step typically runs as part of the CI workflow:

In CI: verify docs build without errors

dotnet build -warnaserror:CS1591 # XML doc completeness docfx metadata docfx.json # API metadata extraction docfx build docfx.json --warningsAsErrors # Full doc site build

This catches documentation regressions (missing docs, broken cross-references) before they reach the main branch.

API Changelog Patterns

Breaking Change Documentation

Document breaking changes with a structured format that consumers can quickly scan:

Breaking Changes in v3.0

Removed APIs

Changed Behavior

• WidgetService.CreateAsync now validates name uniqueness within a category. Previously, duplicate names were silently allowed.
• Widget.Status defaults to Draft instead of Active. Existing code that assumes newly created widgets are active must call widget.Activate().

New Required Dependencies

• Microsoft.Extensions.Caching.Memory is now a required dependency for WidgetService. Register with builder.Services.AddMemoryCache().

Migration Guides Between Major Versions

Structure migration guides by the action required:

Migrating from v2.x to v3.0

Step 1: Update Package References

<!-- Before -->
<PackageReference Include="My.Library" Version="2.*" />

<!-- After -->
<PackageReference Include="My.Library" Version="3.0.0" />

Step 2: Fix Compilation Errors

Async API Changes

All synchronous methods have been removed. Replace synchronous calls with async equivalents:

// Before (v2.x)
var widget = service.Create("name");

// After (v3.0)
var widget = await service.CreateAsync("name", cancellationToken);

Generic Repository Interface

// Before (v2.x)
public class MyRepo : IWidgetRepository { }

// After (v3.0)
public class MyRepo : IWidgetRepository<Widget> { }

Step 3: Update Behavioral Assumptions

- Check all code paths that assume Widget.Status == Active
 after creation

- Add builder.Services.AddMemoryCache()
 to DI registration

### Deprecated API Tracking

Use the `[Obsolete]` attribute with message pointing to the replacement. Document deprecation timelines:

```csharp
/// <summary>
/// Creates a widget synchronously.
/// </summary>
/// <remarks>
/// This method will be removed in v4.0. Use
/// <see cref="CreateAsync(string, CancellationToken)"/> instead.
/// </remarks>
[Obsolete("Use CreateAsync instead. This method will be removed in v4.0.", error: false)]
public Widget Create(string name)
{
}

Track deprecated APIs in a dedicated document:

# Deprecated APIs

| API | Deprecated In | Removed In | Replacement |
|-----|---------------|------------|-------------|
| `WidgetService.Create(string)` | v2.5 | v4.0 (planned) | `CreateAsync(string, CancellationToken)` |
| `Widget.Name` setter | v3.0 | v4.0 (planned) | `WidgetService.RenameAsync(Guid, string)` |
| `WidgetOptions.EnableCache` | v3.1 | v5.0 (planned) | `WidgetOptions.CachePolicy` |

For changelog format conventions and SemVer versioning strategy, see [skill:dotnet-release-management].

Versioned API Documentation

Version Selectors in Doc Sites

DocFX versioned docs:

DocFX supports version-specific metadata extraction by targeting different project versions:

{
  "metadata": [
    {
      "src": [{ "files": ["src/**/*.csproj"], "src": ".." }],
      "dest": "api/v2",
      "properties": { "TargetFramework": "net8.0" },
      "globalNamespaceId": "v2"
    }
  ]
}

Maintain separate branches or tags for each major version, and build documentation from each:

# Build docs for v2.x (current branch)
docfx build docfx.json

# Build docs for v1.x (from tag)
git checkout v1.x
docfx build docfx.json --output _site/v1
git checkout main

Starlight versioned docs:

Use directory-based versioning or the @lorenzo_lewis/starlight-utils
 plugin. See [skill:dotnet-documentation-strategy] for Starlight versioning setup.

Docusaurus versioned docs:

Docusaurus has built-in versioning with npx docusaurus docs:version
. See [skill:dotnet-documentation-strategy] for Docusaurus versioning setup.

Maintaining Docs for Multiple Active Versions

When supporting multiple active major versions simultaneously:

- Branch-per-major-version strategy: Maintain docs/v1
, docs/v2
 directories on the main branch, or separate v1.x
, v2.x
 branches

- Shared conceptual docs: Keep version-independent guides (architecture, concepts) in a shared location, version-specific API reference in separate directories

- Version banner: Add a notification banner on older version docs pointing to the latest version

URL Patterns

Consistent URL patterns for versioned API docs:

https://docs.mylib.dev/                     # Latest stable version
https://docs.mylib.dev/v2/                  # Specific version
https://docs.mylib.dev/v2/api/WidgetService # Specific type in specific version
https://docs.mylib.dev/latest/              # Alias for latest stable
https://docs.mylib.dev/next/                # Pre-release / unreleased docs

Configure redirects so unversioned URLs point to the latest stable version. This ensures existing links remain valid when a new version is published.

Agent Gotchas

- 
Do not generate OpenAPI spec configuration -- OpenAPI generation setup (builder.Services.AddOpenApi()
, document transformers, Swashbuckle migration) belongs to [skill:dotnet-openapi]. This skill covers using the generated OpenAPI output as documentation.

- 
Do not write XML doc comment syntax guidance -- XML tag syntax, conventions, <inheritdoc>
, and GenerateDocumentationFile
 belong to [skill:dotnet-xml-docs]. This skill covers the pipeline from XML docs to generated documentation sites.

- 
Do not generate CI deployment YAML -- doc site deployment workflows (GitHub Pages actions, DocFX deploy) belong to [skill:dotnet-gha-deploy]. This skill covers doc build validation and local generation.

- 
docfx metadata
 requires a buildable project -- the project must compile successfully for DocFX to extract API metadata. Always run dotnet build
 before docfx metadata
 in CI pipelines.

- 
DocFX is community-maintained since November 2022 -- Microsoft transferred the repository. It remains actively maintained and widely used. For new projects evaluating alternatives, see [skill:dotnet-documentation-strategy].

- 
DocFX modern
 template requires v2.75+ -- earlier versions use the default
 template which does not include Mermaid support or modern styling. Check the installed version with docfx --version
.

- 
-warnaserror:CS1591
 should apply only to public library projects -- applying it to test projects, console apps, or internal tools creates unnecessary documentation burden. Use MSBuild conditions to target only published packages.

- 
API filtering with filterConfig.yml
 uses UID regex, not namespace strings -- the pattern ^MyLibrary\.Internal\.
 matches UIDs that start with that prefix. Test filter patterns with docfx metadata --log verbose
 to verify correct filtering.

- 
Breaking change documentation must include migration code examples -- a table listing removed APIs without showing the replacement code is insufficient. Always include before/after code snippets.

- 
Versioned doc URLs must redirect unversioned paths to latest stable -- do not break existing links when publishing a new version. Configure server-side redirects or a client-side redirect page at the root URL.

- 
OpenAPI UI (Scalar, Swagger UI) should only be exposed in development -- wrap MapScalarApiReference
 and UseSwaggerUI
 in if (app.Environment.IsDevelopment())
 guards. Production exposure of interactive API docs is a security consideration.