XML Documentation

The JsonSchemaGenerator automatically loads .NET XML Documentation files to populate the JSON Schema/Swagger/OpenAPI attributes summary, description 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.

Define 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; }

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