Swashbuckle.AspNetCore <example> not working for me

Question

I am trying to set up examples using tag but, it is not working for me. I am using Swashbuckle.AspNetCore library.

Some code samples are below,

1. Added the following to my csproj. file

<GenerateDocumentationFile>true</GenerateDocumentationFile>

2. Program.cs

            builder.Services.AddSwaggerGen(options =>
            {
                options.OperationFilter<SwaggerDefaultValues>();
                var filePath = Path.Combine(System.AppContext.BaseDirectory, "My.xml");
                options.IncludeXmlComments(filePath);

            });

3. Controller looks like,

[Authorize]
[ApiController]
[ApiVersion("1.0")]
[Route("[controller]")]
[Route("v{version:apiVersion}/[controller]")]
[Produces("application/json")]
public class MyController : ControllerBase
{
}

4. My method looks like,

/// <summary>
    /// Method to Post an Incident
    /// </summary>
    /// <param name="initiateRequest" example="FORM_CODE"></param>
    [ProducesResponseType(typeof(InitiateResponseDTO), StatusCodes.Status201Created)]
    [ProducesResponseType(typeof(ExceptionDetails), StatusCodes.Status400BadRequest)]
    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
    [ProducesResponseType(StatusCodes.Status500InternalServerError)]
    [HttpPost]
public async Task<ActionResult<InitiateResponseDTO>> PostAsync(MyRequest myRequest)
    {
//Logic

        return StatusCode(StatusCodes.Status201Created, InitiateResponseDTO);
    }

5. MyDTO looks like,

/// <summary>
/// Initiate Response DTO
/// </summary>
public class InitiateResponseDTO
{
    /// <summary>
    /// IncidentId 
    /// </summary>
    /// <example>985769890</example>
    public int IncidentId { get; set; }
}

6. Exception Details Class

/// <summary>
    /// Exception Details class
    /// </summary>
    public class ExceptionDetails
    {
        /// <summary>
        /// HTTP status code for the exception.
        /// </summary>
        /// <example>400</example>
        public int StatusCode { get; set; } = (int)HttpStatusCode.InternalServerError;

        /// <summary>
        /// (Friendly) message about the exception.
        /// </summary>
        /// <example>Invalid form code supplied: FORM_CODE</example>
        public string Message { get; set; } = "An error occured";

        /// <summary>
        /// Error code for the returned error.
        /// </summary>
        /// <example>UNKNOWN_FORM</example>
        public string ErrorCode { get; set; } = ErrorCodes.Generic;

        /// <summary>
        /// Exception Target denoting the method in which the error occurred.
        /// </summary>
        /// <example>MoveNext <- Method name from which the error occurred</example>
        public string? Target { get; set; }

        /// <summary>
        /// InnerError message denoting the StackTrace.
        /// </summary>
        /// <example> Some Sample</example>
public string? InnerError { get; set; }
}

Still in Swagger UI, I don't see the example values,

Is there anything incorrect with the config? I am using Swashbuckle.AspNetCore 6.4.0

Answer 1

One simple option would be to decorate your properties with the [DefaultValue]

/// <summary>
/// Initiate Response DTO
/// </summary>
public class InitiateResponseDTO
{
    /// <summary>
    /// IncidentId 
    /// </summary>
    /// <example>985769890</example>
    [DefaultValue(985769890)]
    public int IncidentId { get; set; }
}

Depending on how the serialization is done in your project, it should work.

There is also the possibility to look into the Swashbuckle.AspNetCore.Filters Nuget library to setup your examples as you like, but it requires more work: https://github.com/mattfrear/Swashbuckle.AspNetCore.Filters#automatic-annotation