xml-docs-and-openapi
How XML documentation comments on requests, entities and presentation members become the API documentation (OpenAPI and Scalar, GraphQL descriptions, MCP tool descriptions), and the generator gotchas. Use when adding or changing a public type, property, endpoint or request model.
Install
npx skills add https://github.com/LeanMeanCleanApps/CleanMinimalApi/tree/main/.agents/skills/xml-docs-and-openapi
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install leanmeancleanapps-cleanminimalapi@llmmart
git clone https://github.com/LeanMeanCleanApps/CleanMinimalApi.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole leanmeancleanapps/cleanminimalapi collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
XML docs and API documentation
The rule
The API documentation is generated from XML comments, so the comments are the documentation. GenerateDocumentationFile is on for every project. Missing comments (CS1591) aren't build errors, but every request, entity and public presentation member has them anyway.
Where the comments end up:
| Comment on | Shows up as |
|---|---|
Application request properties and entity record <param> tags |
Schema and field descriptions (OpenAPI, GraphQL) |
Endpoint or tool <summary>, <remarks>, <param>, <response> |
Operation summary, description, parameter text and response codes |
Request model <example> |
The example value in the API reference |
Steps
- Requests: a
<summary>on the class saying what the use case does, and one on each property saying what it means and its allowed values. - Entity records: a
<summary>on the record and a<param>for each positional parameter. - Write for the person calling the API: plain sentences, units and ranges, what an empty value means.
- Endpoint and tool comments are covered by
expose-a-use-casefor this template. - Run the app and read the result in the API reference before you call it done.
Example
// src/Application/Movies/Entities/MovieSummary.cs
/// <summary>
/// A movie in a list, with how many reviews it has and their average star rating instead of the reviews themselves.
/// </summary>
/// <param name="Id">The unique identifier of the movie.</param>
/// <param name="Title">The title of the movie.</param>
/// <param name="ReviewCount">The number of reviews written about the movie.</param>
/// <param name="AverageStars">The average star rating to one decimal place, or null when the movie has no reviews.</param>
public record MovieSummary(Guid Id, string Title, int ReviewCount, double? AverageStars);
Don't
- Document an injected
[FromServices] ISender senderparameter. The .NET 10 OpenAPI generator puts that text on the request body instead. Leave it undocumented;NoWarn 1573in the Presentation project allows that. - Copy the member name as the summary ("Gets the title").
- Leave
TODOor placeholder comments.
Check
dotnet build
dotnet test --filter "FullyQualifiedName~OpenApi"
Files (cleanminimalapi)
-
SKILL.md 2.6 KB
--- name: xml-docs-and-openapi description: How XML documentation comments on requests, entities and presentation members become the API documentation (OpenAPI and Scalar, GraphQL descriptions, MCP tool descriptions), and the generator gotchas. Use when adding or changing a public type, property, endpoint or request model. metadata: scope: shared --- # XML docs and API documentation ## The rule The API documentation is generated from XML comments, so the comments are the documentation. `GenerateDocumentationFile` is on for every project. Missing comments (CS1591) aren't build errors, but every request, entity and public presentation member has them anyway. Where the comments end up: | Comment on | Shows up as | | --- | --- | | Application request properties and entity record `<param>` tags | Schema and field descriptions (OpenAPI, GraphQL) | | Endpoint or tool `<summary>`, `<remarks>`, `<param>`, `<response>` | Operation summary, description, parameter text and response codes | | Request model `<example>` | The example value in the API reference | ## Steps 1. Requests: a `<summary>` on the class saying what the use case does, and one on each property saying what it means and its allowed values. 2. Entity records: a `<summary>` on the record and a `<param>` for each positional parameter. 3. Write for the person calling the API: plain sentences, units and ranges, what an empty value means. 4. Endpoint and tool comments are covered by `expose-a-use-case` for this template. 5. Run the app and read the result in the API reference before you call it done. ## Example ```csharp // src/Application/Movies/Entities/MovieSummary.cs /// <summary> /// A movie in a list, with how many reviews it has and their average star rating instead of the reviews themselves. /// </summary> /// <param name="Id">The unique identifier of the movie.</param> /// <param name="Title">The title of the movie.</param> /// <param name="ReviewCount">The number of reviews written about the movie.</param> /// <param name="AverageStars">The average star rating to one decimal place, or null when the movie has no reviews.</param> public record MovieSummary(Guid Id, string Title, int ReviewCount, double? AverageStars); ``` ## Don't - Document an injected `[FromServices] ISender sender` parameter. The .NET 10 OpenAPI generator puts that text on the request body instead. Leave it undocumented; `NoWarn 1573` in the Presentation project allows that. - Copy the member name as the summary ("Gets the title"). - Leave `TODO` or placeholder comments. ## Check ``` bash dotnet build dotnet test --filter "FullyQualifiedName~OpenApi" ```
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.