DEV Community

Supraja Tangella
Supraja Tangella

Posted on

๐—” ๐—ค๐˜‚๐—ถ๐—ฐ๐—ธ ๐—š๐˜‚๐—ถ๐—ฑ๐—ฒ - ๐—ข๐—ฝ๐—ฒ๐—ป๐—”๐—ฃ๐—œ ๐— ๐—ฒ๐˜๐—ฎ๐—ฑ๐—ฎ๐˜๐—ฎ

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.

Image description

Top comments (1)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.