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.
Top comments (1)
Some comments may only be visible to logged-in visitors. Sign in to view all comments.