Swashbuckle C# (.NET): तरीके, उदाहरण, इंस्टॉलेशन

Swashbuckle क्या है और इसकी आवश्यकता क्यों है?

Swashbuckle .NET प्लेटफॉर्म के लिए एक शक्तिशाली लाइब्रेरी है जो OpenAPI (पहले Swagger के नाम से जाना जाता था) मानक के आधार पर आपके Web API के लिए स्वचालित रूप से इंटरैक्टिव डॉक्यूमेंटेशन तैयार करती है। यह सीधे ASP.NET Core एप्लिकेशन में एकीकृत होती है और डेवलपर्स, टेस्टर्स और API उपभोक्ताओं को आपके एंडपॉइंट्स को आसानी से समझने और उनके साथ इंटरैक्ट करने में मदद करती है।

इसकी आवश्यकता क्यों है?

डॉक्यूमेंटेशन ऑटोमेशन: आपको मैन्युअल रूप से डॉक्यूमेंटेशन लिखने और अपडेट करने की ज़रूरत नहीं है। Swashbuckle आपके कंट्रोलर, मॉडल और एट्रीब्यूट्स का विश्लेषण करके तुरंत अप-टू-डेट डॉक्यूमेंटेशन तैयार करता है।
इंटरैक्टिव इंटरफ़ेस (Swagger UI): लाइब्रेरी एक वेब इंटरफ़ेस प्रदान करती है जहाँ आप सभी एंडपॉइंट्स, उनके पैरामीटर, डेटा मॉडल देख सकते हैं और सीधे ब्राउज़र से टेस्ट रिक्वेस्ट भी कर सकते हैं।
मानकीकरण: OpenAPI एक उद्योग मानक है। तैयार डॉक्यूमेंटेशन का उपयोग विभिन्न भाषाओं (JavaScript, Python, Java आदि) में क्लाइंट SDK स्वचालित रूप से जनरेट करने के लिए किया जा सकता है।
टेस्टिंग और डिबगिंग को आसान बनाता है: डेवलपर्स और QA इंजीनियर Postman जैसे तीसरे पक्ष के टूल के बिना भी API का तेज़ी से परीक्षण कर सकते हैं (हालाँकि Postman भी OpenAPI स्पेसिफिकेशन को इम्पोर्ट कर सकता है)।

Swashbuckle दो मुख्य घटकों से बना है: Swashbuckle.AspNetCore.Swagger (OpenAPI की JSON स्पेसिफिकेशन जनरेट करना) और Swashbuckle.AspNetCore.SwaggerUI (इंटरैक्टिव इंटरफ़ेस प्रदर्शित करना)।

इंस्टॉलेशन

Swashbuckle NuGet पैकेज मैनेजर के माध्यम से इंस्टॉल किया जाता है। आप पैकेज मैनेजर कंसोल, .NET CLI या Visual Studio इंटरफ़ेस का उपयोग कर सकते हैं।

.NET CLI के माध्यम से (अनुशंसित)

dotnet add package Swashbuckle.AspNetCore

Visual Studio में Package Manager Console के माध्यम से

Install-Package Swashbuckle.AspNetCore

यह कमांड मुख्य पैकेज इंस्टॉल करेगा जिसमें सभी आवश्यक घटक शामिल हैं: Swagger, SwaggerUI और Swashbuckle.Core।

कोड उदाहरण के साथ त्वरित शुरुआत

ASP.NET Core Web API के लिए Swashbuckle की न्यूनतम सेटअप देखते हैं।

1. एक नया Web API प्रोजेक्ट बनाएं

dotnet new webapi -n MySwaggerApi
cd MySwaggerApi

2. Swashbuckle जोड़ें

dotnet add package Swashbuckle.AspNetCore

3. Program.cs कॉन्फ़िगर करें

Program.cs फ़ाइल खोलें और निम्नलिखित कोड जोड़ें:

using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

// Swagger सेवाएँ जोड़ें
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "My Awesome API",
        Version = "v1",
        Description = "Swashbuckle प्रदर्शित करने के लिए एक उदाहरण API"
    });
});

var app = builder.Build();

// Swagger के लिए middleware सक्षम करें
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

// एक सरल एंडपॉइंट का उदाहरण
var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast");

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}