XML comments

As explained in Building Web APIs with ASP.NET Core

XML documentation is structured source-code documentation written in XML comment elements and consumed by development or documentation tools.

XML comments are structured C# source-code documentation written with triple slashes. Development and documentation tools can use elements such as <summary>, <param>, and <returns> to describe API actions and their inputs and outputs. section 11.2.2 section 11.2.3

To expose XML comments through SwaggerUI:

• Place three slashes above an action method and its attributes; Visual Studio generates documentation boilerplate and identifies parameters such as RegisterDTO input. section 11.2.3
• Fill the <summary>, <param>, and <returns> elements with the endpoint’s purpose, input description, and response. section 11.2.3
• Enable <GenerateDocumentationFile>true</GenerateDocumentationFile> in the project file; optionally suppress warning 1591 for undocumented members. section 11.2.3
• Use Assembly and IncludeXmlComments to locate the generated XML file and make it available to Swashbuckle. section 11.2.3

Documenting an endpoint

/// <summary>\n/// Registers a new user.\n/// </summary>\n/// <param name="input">A DTO containing the user data.</param>\n/// <returns>A 201 - Created Status Code in case of success.</returns>\npublic async Task<ActionResult> Register(RegisterDTO input) section 11.2.3

Figure 11.1 XML documentation fetched by Swashbuckle and used in SwaggerUI

SwaggerUI can display XML documentation fetched through Swashbuckle, turning source comments into endpoint reference information. section 11.2.3

How Building Web APIs with ASP.NET Core covers it

How deep it goes

Explains syntax, generated tags, project-file configuration, and Swashbuckle integration, but does not catalog every supported XML tag.

Examples

Uses Register and Login actions, DTO parameters, generated XML files, project configuration, and SwaggerUI output.

What it assumes

Assumes a C# API project with controller actions and Swashbuckle, while demonstrating the comment syntax from the beginning.

What you can do after

Builds endpoint documentation from C# comments and displays it through Swashbuckle in SwaggerUI.

How it connects

Connects C#, XML documentation, IDEs, Swashbuckle, SwaggerUI, API documentation, and HTTP endpoints.

liveBookmanning.com

Read Building Web APIs with ASP.NET Core on liveBook Get the book at manning.com

Related concepts

• XML documentation fileproduces · An XML documentation file is a generated XML artifact containing structured documentation extracted from specially formatted source-code comments.
• SwaggerOperation attributealternative to · A Swashbuckle annotation attribute that supplies descriptive metadata for an API operation during OpenAPI document generation.
• API documentationuses · API documentation is written or generated material describing an application programming interface’s capabilities, operations, inputs, outputs, behavior, and usage.
• Swashbuckle.AspNetCore.Annotationsalternative to · Swashbuckle.AspNetCore.Annotations is a .NET package that provides annotation attributes for customizing generated OpenAPI documentation.

This explainer was generated by Manning's knowledge graph from the text of Building Web APIs with ASP.NET Core. The section links point to the parts of the book it draws on.