How to add parameters description in minimal api using swagger

better use xml comments

give three slashes and it will automatically pick the parameter

to enable xml comments follow below code

services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "MyCustomAPI", Version = "v1" });
// generate the XML docs that'll drive the swagger docs
var xmlFile = $"
{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
});

//
/// Returns a collection of URLs
///
/// "slugs">list of slugs to retrieve
///
/// Sample request:
///
/// Get /api/slugscollection/(d25tRx, fN5jpz)
///
///
/// IEnumerable of slugs
/// code="200">If all requested items are
/// found
/// code="400">If slugs parameter is missing
/// code="404">If number of records found doesn't equal
/// number of records requested
[HttpGet("({slugs})", Name = "GetSlugCollection")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task GetSlugCollection([ModelBinder(BinderType = typeof(ArrayModelBinder))] IEnumerable slugs)
{ ...
}

to avoid warnings (it give warning for all those methods where you missed to give atleast one xml comment)

double click on API project name to open csproj file and copy paste

true
$(NoWarn);1591

2 Replies

Know the answer? Post it — somebody with the same question will find it here.

Sachin Singh4y ago
better use xml comments
give three slashes and it will automatically pick the parameter
to enable xml comments follow below code
services.AddSwaggerGen(c =>
  {
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "MyCustomAPI", Version = "v1" });

    // generate the XML docs that'll drive the swagger docs
    var xmlFile = $"
      {Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
  });
//

/// Returns a collection of URLs
///
/// "slugs">list of slugs to retrieve
///
/// Sample request:
///
///     Get /api/slugscollection/(d25tRx, fN5jpz)
///
///
/// IEnumerable of slugs
/// code="200">If all requested items are
/// found
/// code="400">If slugs parameter is missing
/// code="404">If number of records found doesn't equal
/// number of records requested
[HttpGet("({slugs})", Name = "GetSlugCollection")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task GetSlugCollection([ModelBinder(BinderType = typeof(ArrayModelBinder))] IEnumerable slugs)
{ ...

}
to avoid warnings (it give warning for all those methods where you missed to give atleast one xml comment)
double click on API project name to open csproj file and copy paste
  true
  $(NoWarn);1591
Vishal Yelve4y ago
This might help

Install package
Swashbuckle.AspNetCore.Annotations
In Program.cs
builder.Services.AddSwaggerGen(x =>
{
  x.EnableAnnotations();
});

// app.MapGet("/hi", [SwaggerOperation(Summary = "summary001", Description = "description001 `adads`")] () => "Hi");

app.MapGet("/hi", () => "Hi")
  .WithMetadata(new SwaggerOperationAttribute("summary001", "description001"));