dotnet-api-docs

Name: dotnet-api-docs
Author: wshaddix

65stars10forks

How to install dotnet-api-docs?

wshaddix/dotnet-skills/dotnet-api-docs

$npx -y skills add wshaddix/dotnet-skills --skill dotnet-api-docs

Installs into the current project.

Summary

Generating API documentation. DocFX setup, OpenAPI-as-docs, doc-code sync, versioned docs.

Files · 1

View on GitHub

SKILL.md

1	# dotnet-api-docs
2
3	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).
4
5	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.
6
7	Scope boundary: This skill owns API documentation generation from code -- the tooling and processes that turn source code, XML comments, and OpenAPI specs into browsable documentation. XML documentation comment syntax and authoring conventions are owned by [skill:dotnet-xml-docs]. OpenAPI specification generation and Swashbuckle migration are owned by [skill:dotnet-openapi]. CI/CD deployment of documentation sites is owned by [skill:dotnet-gha-deploy]. Documentation platform selection (Starlight vs DocFX vs Docusaurus) is owned by [skill:dotnet-documentation-strategy].
8
9	Out of scope: XML documentation comment syntax and authoring -- see [skill:dotnet-xml-docs]. OpenAPI spec generation and configuration (Swashbuckle, Microsoft.AspNetCore.OpenApi setup) -- 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].
10
11	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.
12
13	---
14
15	## DocFX Setup for .NET API Reference
16
17	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.
18
19	### Installation
20
21	```bash
22	# Install DocFX as a .NET global tool
23	dotnet tool install -g docfx
24
25	# Or as a local tool (recommended for team consistency)
26	dotnet new tool-manifest
27	dotnet tool install docfx
28	```
29
30	### Configuration (`docfx.json`)
31
32	```json
33	{
34	"metadata": [
35	{
36	"src": [
37	{
38	"files": ["src/*/.csproj"],
39	"exclude": ["/bin/", "/obj/"],
40	"src": ".."
41	}
42	],
43	"dest": "api",
44	"properties": {
45	"TargetFramework": "net8.0"
46	},
47	"disableGitFeatures": false,
48	"disableDefaultFilter": false
49	}
50	],
51	"build": {
52	"content": [
53	{
54	"files": ["api/**.yml", "api/index.md"]
55	},
56	{
57	"files": [
58	"articles/**.md",
59	"articles/**/toc.yml",
60	"toc.yml",
61	"*.md"
62	]
63	}
64	],
65	"resource": [
66	{
67	"files": ["images/**"]
68	}
69	],
70	"dest": "_site",
71	"globalMetadataFiles": [],
72	"fileMetadataFiles": [],
73	"template": ["default", "modern"],
74	"postProcessors": ["ExtractSearchIndex"],
75	"markdownEngineName": "markdig",
76	"noLangKeyword": false,
77	"keepFileLink": false,
78	"cleanupCacheHistory": false,
79	"disableGitFeatures": false,
80	"globalMetadata": {
81	"_appTitle": "My.Library API Reference",
82	"_appFooter": "Copyright 2024 My Company",
83	"_enableSearch": true,
84	"_enableNewTab": true
85	}
86	}
87	}
88	```
89
90	### Metadata Extraction
91
92	The `metadata` section controls how DocFX extracts API information from .NET projects:
93
94	```bash
95	# Generate API metadata YAML files from projects
96	docfx metadata docfx.json
97
98	# This creates YAML files in the api/ directory:
99	# api/MyLibrary.WidgetService.yml
100	# api/MyLibrary.Widget.yml
101	# api/toc.yml
102	```
103
104	Key metadata configuration options:
105
106	\| Property \| Purpose \| Default \|
107	\|----------\|---------\|---------\|
108	\| `src.files` \| Project files to extract from \| Required \|
109	\| `dest` \| Output directory for YAML \| `api` \|
110	\| `properties.TargetFramework` \| TFM to build against \| Project default \|
111	\| `disableGitFeatures` \| Skip git blame info \| `false` \|
112	\| `filter` \| Path to API filter YAML \| None (all public APIs) \|
113
114	### API Filtering
115
116	Exclude internal types from the generated documentation:
117
118	```yaml
119	# filterConfig.yml
120	apiRules:
121	- exclude:
122	uidRegex: ^MyLibrary\.Internal\.
123	type: Namespace
124	- exclude:

wshaddixPublisher · 77 listings

Preview

wshaddix/dotnet-skills

# dotnet-api-docs

API documentation generation for .NET projects: DocFX setup for API reference from assemblies (`docfx.json` configuration, metadata extraction, template customi

**Version assumptions:** DocFX v2.x (community-maintained). OpenAPI 3.x via `Microsoft.AspNetCore.OpenApi` (.NET 9+ built-in). Scalar UI for modern OpenAPI visu

**Scope boundary:** This skill owns API documentation generation from code -- the tooling and processes that turn source code, XML comments, and OpenAPI specs i

Repowshaddix/dotnet-skills

License—

TypeSkills

CategoryDocumentation

UpdatedFeb 2026

Repo stars65

First seenJul 22, 2026

People who liked this also viewed

6 picks

Type

dotnet-api-docs

65stars10forks

View on GitHub

How to install dotnet-api-docs?

wshaddix/dotnet-skills/dotnet-api-docs

$npx -y skills add wshaddix/dotnet-skills --skill dotnet-api-docs

Installs into the current project.

Summary

Generating API documentation. DocFX setup, OpenAPI-as-docs, doc-code sync, versioned docs.

Files · 1

View on GitHub

SKILL.md

1	# dotnet-api-docs
2
3	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).
4
5	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.
6
7	Scope boundary: This skill owns API documentation generation from code -- the tooling and processes that turn source code, XML comments, and OpenAPI specs into browsable documentation. XML documentation comment syntax and authoring conventions are owned by [skill:dotnet-xml-docs]. OpenAPI specification generation and Swashbuckle migration are owned by [skill:dotnet-openapi]. CI/CD deployment of documentation sites is owned by [skill:dotnet-gha-deploy]. Documentation platform selection (Starlight vs DocFX vs Docusaurus) is owned by [skill:dotnet-documentation-strategy].
8
9	Out of scope: XML documentation comment syntax and authoring -- see [skill:dotnet-xml-docs]. OpenAPI spec generation and configuration (Swashbuckle, Microsoft.AspNetCore.OpenApi setup) -- 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].
10
11	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.
12
13	---
14
15	## DocFX Setup for .NET API Reference
16
17	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.
18
19	### Installation
20
21	```bash
22	# Install DocFX as a .NET global tool
23	dotnet tool install -g docfx
24
25	# Or as a local tool (recommended for team consistency)
26	dotnet new tool-manifest
27	dotnet tool install docfx
28	```
29
30	### Configuration (`docfx.json`)
31
32	```json
33	{
34	"metadata": [
35	{
36	"src": [
37	{
38	"files": ["src/*/.csproj"],
39	"exclude": ["/bin/", "/obj/"],
40	"src": ".."
41	}
42	],
43	"dest": "api",
44	"properties": {
45	"TargetFramework": "net8.0"
46	},
47	"disableGitFeatures": false,
48	"disableDefaultFilter": false
49	}
50	],
51	"build": {
52	"content": [
53	{
54	"files": ["api/**.yml", "api/index.md"]
55	},
56	{
57	"files": [
58	"articles/**.md",
59	"articles/**/toc.yml",
60	"toc.yml",
61	"*.md"
62	]
63	}
64	],
65	"resource": [
66	{
67	"files": ["images/**"]
68	}
69	],
70	"dest": "_site",
71	"globalMetadataFiles": [],
72	"fileMetadataFiles": [],
73	"template": ["default", "modern"],
74	"postProcessors": ["ExtractSearchIndex"],
75	"markdownEngineName": "markdig",
76	"noLangKeyword": false,
77	"keepFileLink": false,
78	"cleanupCacheHistory": false,
79	"disableGitFeatures": false,
80	"globalMetadata": {
81	"_appTitle": "My.Library API Reference",
82	"_appFooter": "Copyright 2024 My Company",
83	"_enableSearch": true,
84	"_enableNewTab": true
85	}
86	}
87	}
88	```
89
90	### Metadata Extraction
91
92	The `metadata` section controls how DocFX extracts API information from .NET projects:
93
94	```bash
95	# Generate API metadata YAML files from projects
96	docfx metadata docfx.json
97
98	# This creates YAML files in the api/ directory:
99	# api/MyLibrary.WidgetService.yml
100	# api/MyLibrary.Widget.yml
101	# api/toc.yml
102	```
103
104	Key metadata configuration options:
105
106	\| Property \| Purpose \| Default \|
107	\|----------\|---------\|---------\|
108	\| `src.files` \| Project files to extract from \| Required \|
109	\| `dest` \| Output directory for YAML \| `api` \|
110	\| `properties.TargetFramework` \| TFM to build against \| Project default \|
111	\| `disableGitFeatures` \| Skip git blame info \| `false` \|
112	\| `filter` \| Path to API filter YAML \| None (all public APIs) \|
113
114	### API Filtering
115
116	Exclude internal types from the generated documentation:
117
118	```yaml
119	# filterConfig.yml
120	apiRules:
121	- exclude:
122	uidRegex: ^MyLibrary\.Internal\.
123	type: Namespace
124	- exclude:

wshaddixPublisher · 77 listings

Preview

wshaddix/dotnet-skills

# dotnet-api-docs

API documentation generation for .NET projects: DocFX setup for API reference from assemblies (`docfx.json` configuration, metadata extraction, template customi

**Version assumptions:** DocFX v2.x (community-maintained). OpenAPI 3.x via `Microsoft.AspNetCore.OpenApi` (.NET 9+ built-in). Scalar UI for modern OpenAPI visu

**Scope boundary:** This skill owns API documentation generation from code -- the tooling and processes that turn source code, XML comments, and OpenAPI specs i

Repowshaddix/dotnet-skills

License—

TypeSkills

CategoryDocumentation

UpdatedFeb 2026

Repo stars65

First seenJul 22, 2026

People who liked this also viewed

6 picks

Type