XML Documentation

The JsonSchemaGenerator automatically loads .NET XML Documentation files to populate the JSON Schema/Swagger/OpenAPI attributes summary, description, example and others.

The XML file is searched in the directory of the type's assembly with the assembly file name but with the file extension .xml. This XML file is only generated when enabled in the project settings. For netcore projects, use <GenerateDocumentationFile>true</GenerateDocumentationFile>

Define property examples

The schema example object can be set with the example xml docs:

/// <example>
/// { "name": "Smith" }
/// </example>
public class Person
{
    public string Name { get; set; }

Code readability tip

With the <include tag you can load common xml code from a file, read this article for more information.

Possible issues

The XML Documentation reader uses reflection to support multiple platforms in a single PCL and multiple .NET Standard versions. In order to work, the following types must be available:

• System.IO.File
• System.IO.Path
• System.Xml.XPath.Extensions

For examples to be shown on the Swagger UI you must turn off the AllowNullableBodyParameters. If you do not turn it off, the only example you will get is a null/empty example. Example:

settings.GeneratorSettings.AllowNullableBodyParameters = false;

.NET Core

To make the required types available in a .NET Core process (i.e. in your ASP.NET Core application), you may need to install the following NuGet packages:

• System.IO.FileSystem
• System.Xml.XPath.XDocument

If you are using .net core 3.0 or later and enabled <PublishTrimmed>true</PublishTrimmed> in your .csproj, those types can be trimmed, resulting in a schema with missing XML docs (for example, a swagger.json or a swagger-ui without docs, despite the .xml file being present). To avoid that, include the following assemblies as a "trimmer root":

  <ItemGroup>
    <TrimmerRootAssembly Include="System.IO.FileSystem" />
    <TrimmerRootAssembly Include="System.Xml.XPath.XDocument" />
    <TrimmerRootAssembly Include="System.Xml.Linq" />
  </ItemGroup>