NetCore: How to provide SwaggerUI with an example?

Question

When I have set up a Controller function with netcore6 like this:

[HttpPost]
[Route(nameof(UpdateMaterialCalculationConfiguration))]
[ProducesResponseType((int)HttpStatusCode.OK, Type = typeof(EditorResponse<EditorMaterialCalculationConfigurationResponse>))]
public IActionResult UpdateMaterialCalculationConfiguration([Required][FromBody] EditorUpdateMaterialCalculationConfigurationRequest request)
{
  ...
}

The Swagger UI will provide you with a basic json with the names of the properties and their datatype, like this:

{
  "MaterialId": "string",
  "MaterialType": "string",
  ...
}

But is it possible to describe - in C# - a specific example?

Is this what you want? https://stackoverflow.com/questions/48210087/swagger-default-value-for-parameter — Leviathan, Jul 28 '23 at 08:30
follow sample project https://github.com/upendarreddy678/SwaggerUI-Example — Upender Reddy, Jul 31 '23 at 06:20

Upender Reddy · Accepted Answer · 2023-07-31T06:19:03.083

Generating XML File for the Project and add it to swagger it will help you generating swagger Documentation. Follow below steeps Step:1 Suppose your Project is TestAPI add below lines to TestAPI.csproj file

<PropertyGroup>
  <GenerateDocumentationFile>True</GenerateDocumentationFile>
  <DocumentationFile>TestAPI.xml</DocumentationFile>
</PropertyGroup>

After saving you will get TestAPI.xml file in your project directory.

Step:2 configure builder.Services.AddSwaggerGen() as below. it will add TestAPI.xml file to your swagger documentation

 builder.Services.AddSwaggerGen(c =>
  {
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    if (File.Exists(xmlFile))
    {
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath, includeControllerXmlComments: true);
    }
 });

what ever written in summary will give you as shown in below

    /// <summary>
    /// Test Service is used To 
    /// </summary>
    /// <param name="id"> key of The Record </param>
    /// <response code="200">On Successfull Request</response>
    [HttpGet("TestServe")]
    public IActionResult TestServe(string id)
    {
        return Ok();
    }

step:3 decorate property with example as shown in below it modify the json value with example value.

    /// <summary>
    /// To Create Test
    /// </summary>
    /// <param name="Inp">Sample Request</param>
    /// <response code="200">On Successfull Create</response>
    [HttpPost("TestCreate")]
    public IActionResult TestCreate(MyTestClass Inp)
    {
        return Ok();
    }

    public class MyTestClass
    {
        /// <example>1</example>
        public int Id { get; set; }
        /// <example>Upender</example>
        public string? Name { get; set; }
    }

follow SampleProject

In Visual studio press `///` it will automatically generate sample `Summary` — Upender Reddy, Jul 28 '23 at 09:13

score 0 · Answer 2 · answered Jul 28 '23 at 08:34

If you want to extend SwaggerUI with some request example, you can use XML comments for your method:

/// <summary>
/// Creates an Employee.
/// </summary>
/// <remarks>
/// Sample request:
/// 
///     POST api/Employee
///     {        
///       "firstName": "Mike",
///       "lastName": "Andrew",
///       "emailId": "Mike.Andrew@gmail.com"        
///     }
/// </remarks>
/// <param name="employee"></param>

Be aware about XML warnings. More details can be found here: https://code-maze.com/swagger-ui-asp-net-core-web-api/

But if you want to provide a RESPONSE example, you better to youse the OPEN-API approach for your .Net core application: https://learn.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-7.0

Open-api will give you the possibility to control your request\response contracts fully (HTTP code, Body payload, headers, Error messages and etc.)

NetCore: How to provide SwaggerUI with an example?

2 Answers2