𝗔 𝗤𝘂𝗶𝗰𝗸 𝗚𝘂𝗶𝗱𝗲 - 𝗢𝗽𝗲𝗻𝗔𝗣𝗜 𝗠𝗲𝘁𝗮𝗱𝗮𝘁𝗮

If you're working with 𝗔𝗦𝗣.𝗡𝗘𝗧 𝗖𝗼𝗿𝗲 𝗪𝗲𝗯 𝗔𝗣𝗜𝘀 𝗼𝗿 𝗠𝗶𝗻𝗶𝗺𝗮𝗹 𝗔𝗣𝗜𝘀, you’ve probably used Swagger UI. But have you ever wondered 𝗵𝗼𝘄 𝘁𝗵𝗮𝘁 𝗔𝗣𝗜 𝗱𝗼𝗰𝘂𝗺𝗲𝗻𝘁𝗮𝘁𝗶𝗼𝗻 𝗶𝘀 𝗴𝗲𝗻𝗲𝗿𝗮𝘁𝗲𝗱 𝗮𝘂𝘁𝗼𝗺𝗮𝘁𝗶𝗰𝗮𝗹𝗹𝘆?

It’s powered by the 𝗢𝗽𝗲𝗻𝗔𝗣𝗜 𝗺𝗲𝘁𝗮𝗱𝗮𝘁𝗮 collected from your endpoints.

𝗛𝗼𝘄 𝗜𝘁 𝗪𝗼𝗿𝗸𝘀

ASP.NET Core collects metadata from your web API routes and uses it to build an OpenAPI (Swagger) document.

There are two types of APIs:

🔹 Controller-based APIs

These rely on attributes like [HttpGet], [FromBody], and [Produces].
Make sure the controller has the [ApiController] attribute.

🔹 Minimal APIs ( .NET 6/ 7/ 8/ 9)

These use extension methods like .WithSummary(), .WithDescription(), and .WithName() to define metadata manually.

𝗘𝘅𝗮𝗺𝗽𝗹𝗲 (𝗠𝗶𝗻𝗶𝗺𝗮𝗹 𝗔𝗣𝗜 𝗶𝗻 .𝗡𝗘𝗧 𝟵)

app.MapGet("/tasks", () => new[] { "Task 1", "Task 2" })
.WithName("GetAllTasks")
.WithSummary("Gets the list of task items")
.WithDescription("Returns a list of tasks from the system.");

This metadata will appear in:

• Swagger UI: /swagger
• JSON doc: /openapi/v1.json

Advantages:

• Makes your APIs 𝗲𝗮𝘀𝘆 𝘁𝗼 𝘂𝗻𝗱𝗲𝗿𝘀𝘁𝗮𝗻𝗱
• Helps frontend devs 𝗾𝘂𝗶𝗰𝗸𝗹𝘆 𝗲𝘅𝗽𝗹𝗼𝗿𝗲 endpoints
• Builds professional and 𝘀𝗲𝗹𝗳-𝗱𝗼𝗰𝘂𝗺𝗲𝗻𝘁𝗶𝗻𝗴 APIs
• Boosts integration speed and reduces confusion

𝗛𝗮𝘃𝗲 𝘆𝗼𝘂 𝘀𝘁𝗮𝗿𝘁𝗲𝗱 𝘂𝘀𝗶𝗻𝗴 𝘁𝗵𝗲 𝗻𝗲𝘄 .𝗪𝗶𝘁𝗵𝗦𝘂𝗺𝗺𝗮𝗿𝘆() 𝗮𝗻𝗱 .𝗪𝗶𝘁𝗵𝗗𝗲𝘀𝗰𝗿𝗶𝗽𝘁𝗶𝗼𝗻() 𝗺𝗲𝘁𝗵𝗼𝗱𝘀 𝗶𝗻 𝘆𝗼𝘂𝗿 .𝗡𝗘𝗧 𝟵 𝗺𝗶𝗻𝗶𝗺𝗮𝗹 𝗔𝗣𝗜𝘀?
𝗜𝗳 𝗻𝗼𝘁, 𝗻𝗼𝘄’𝘀 𝘁𝗵𝗲 𝘁𝗶𝗺𝗲 𝘁𝗼 𝘁𝗿𝘆 𝘁𝗵𝗲𝗺! 🔧

𝗡𝗼𝘁𝗲: ASP.NET Core does 𝗻𝗼𝘁 use XML <summary> comments for OpenAPI metadata.