# Dotnet API Docs > Generates API documentation. DocFX setup, OpenAPI-as-docs, doc-code sync, versioned docs. - Skill: `rudironsoni/dotnet-api-docs` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add rudironsoni/dotnet-api-docs` - Raw SKILL.md: https://api.skillmd.com/api/skills/rudironsoni/dotnet-api-docs/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing, AI & ML - License: MIT - Author: rudironsoni (https://skillmd.com/u/rudironsoni) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/rudironsoni/dotnet-api-docs --- # 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 `````bash # 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 ```text ### Configuration (`docfx.json`) ```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 } } } ```text ### Metadata Extraction The `metadata` section controls how DocFX extracts API information from .NET projects: ```bash # 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 ```yaml **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: ```yaml # filterConfig.yml apiRules: - exclude: uidRegex: ^MyLibrary\.Internal\. type: Namespace - exclude: hasAttribute: uid: System.ComponentModel.EditorBrowsableAttribute ctorArguments: - System.ComponentModel.EditorBrowsableState.Never ```text Reference the filter in `docfx.json`: ```json { "metadata": [ { "filter": "filterConfig.yml" } ] } ```yaml ### Template Customization DocFX supports template overrides for custom branding: ```text docs/ templates/ custom/ styles/ main.css # Custom CSS overrides partials/ head.tmpl.partial # Custom head section (analytics, fonts) footer.tmpl.partial ```csharp Reference custom templates in `docfx.json`: ```json { "build": { "template": ["default", "modern", "templates/custom"] } } ```text ### Cross-Referencing Between Pages DocFX supports `uid`-based cross-references between API pages and conceptual articles: ```markdown See the @MyLibrary.WidgetService.CreateWidgetAsync(System.String) method for details. For the full API, see . ```text ```yaml # 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 ```markdown --- ## 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: ```csharp // 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(); ```text 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: ```csharp 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 }); } ```text ### Versioned OpenAPI Documents Serve multiple OpenAPI documents for different API versions: ```csharp 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(); ```json ### Exporting OpenAPI for Static Documentation Export the OpenAPI spec at build time for use in static documentation sites: ```bash # 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 ```json Alternatively, use the `Microsoft.Extensions.ApiDescription.Server` package to generate at build time: ```xml all runtime; build; native; contentfiles; analyzers true $(MSBuildProjectDirectory)/../docs/openapi ```text 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: ```xml Source Code (.cs files) | v XML Doc Comments (/// ...) | 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) | ## Detailed Examples See [references/detailed-examples.md](references/detailed-examples.md) for complete code samples and advanced patterns.