Extended Swagger in .net core 6

Hello everybody,

I am going to tell frequently used extended swagger features in this article. The main contents of this article are as follows; summary, remarks, responses.

How and why to use ProducesResponseType attribute ?

Firstly, I start with response.

We have many http status code. The first things that come to mind are 200, 201, 400, 404. We use the ProducesResponseType attribute for these cases.

e.g.;

[ProducesResponseType(StatusCodes.Status200OK, Type = typeof(WeatherForecast[]))]
[ProducesResponseType(StatusCodes.Status400BadRequest, Type = typeof(BadRequestModel))]

result:

How and why to use summary tag ?

We use to explain the api in here.

/// <summary>
/// Return Whole Weather Forecasts
/// </summary>

result:

Warning !!!

We added PropertyGroup in csproj to use tags.

PropertyGroup follow below;

<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
  </PropertyGroup>

Also my csproj :

<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
  </PropertyGroup>
<ItemGroup>
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.2.3" />
  </ItemGroup>
</Project>

Then, We need add swagger option on Program.cs.

Swagger option follow below;

//using System.Reflection;
builder.Services.AddSwaggerGen(options =>{
var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

How and why to use remarks tag ?

Remarks tag provides explanation field for api.

/// <remarks>
///  This api just get to whole **Weather Forecasts**
/// </remarks>

Also, We able to bold words with twice stars.

How and why to use response tag ?

Response tag provides explanation field for responses.

/// <response code="200">Get Weather Forecast</response>
/// <response code="400">Bad Request For Weather Forecast</response>

This project in github. Github: https://github.com/taskinbinbir/SwaggerApp

Good luck :)

References:

https://docs.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-6.0&tabs=visual-studio-code

https://docs.microsoft.com/en-us/dotnet/visual-basic/language-reference/xmldoc/summary#:~:text=of%20the%20object.-,Remarks,displayed%20in%20the%20Object%20Browser.

My article of swagger options: https://taskinbinbir.medium.com/swagger-options-ef35b11a7574