Swagger/OpenAPI C# (.NET) API जनरेशन और दस्तावेज़ीकरण

Swagger/OpenAPI जनरेशन C# (.NET) के लिए

Swagger (अब आधिकारिक रूप से OpenAPI के नाम से जाना जाता है) RESTful API को डिज़ाइन करने, बनाने, दस्तावेज़ित करने और उपयोग करने का एक शक्तिशाली टूल है। .NET इकोसिस्टम में, OpenAPI स्पेसिफिकेशन और इंटरैक्टिव दस्तावेज़ीकरण का ऑटोमैटिक जनरेशन आधुनिक वेब सर्विसेज के विकास का एक अभिन्न हिस्सा बन गया है। इस लेख में, हम विस्तार से जानेंगे कि Swashbuckle.AspNetCore लाइब्रेरी का उपयोग करके C# (.NET) एप्लिकेशन में Swagger/OpenAPI ऑटोमैटिक जनरेशन कैसे सेटअप करें।

Swagger न केवल पढ़ने योग्य दस्तावेज़ीकरण को ऑटोमैटिक रूप से बनाता है, बल्कि ब्राउज़र से सीधे एंडपॉइंट्स को टेस्ट करने के लिए एक इंटरैक्टिव इंटरफ़ेस (Swagger UI) भी प्रदान करता है। यह डेवलपमेंट और टीमों के बीच इंटीग्रेशन को काफी तेज़ करता है।

.NET में Swashbuckle इंस्टॉल और सेटअप करना

शुरू करने के लिए, हमें Swashbuckle.AspNetCore पैकेज इंस्टॉल करना होगा। यह मुख्य पैकेज है जिसमें Swagger जनरेटर, Swagger UI और ASP.NET Core के साथ इंटीग्रेशन शामिल है।

NuGet Package Manager Console के माध्यम से इंस्टॉल करें:

Install-Package Swashbuckle.AspNetCore

या .NET CLI के माध्यम से:

dotnet add package Swashbuckle.AspNetCore

पैकेज इंस्टॉल करने के बाद, Program.cs (या पुराने वर्ज़न के लिए Startup.cs) फ़ाइल में सर्विसेज कॉन्फ़िगर करनी होंगी। .NET 8 और उससे ऊपर के लिए न्यूनतम कॉन्फ़िगरेशन देखें:

var builder = WebApplication.CreateBuilder(args);

// Swagger सर्विसेज जोड़ें
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
    {
        Title = "My API",
        Version = "v1",
        Description = "Swagger दस्तावेज़ीकरण के साथ API का उदाहरण"
    });
});

builder.Services.AddControllers();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });
}

app.UseHttpsRedirection();
app.MapControllers();

app.Run();

Swashbuckle की मुख्य विशेषताएं

• OpenAPI स्पेसिफिकेशन का ऑटोमैटिक जनरेशन — लाइब्रेरी आपके कंट्रोलर, डेटा मॉडल और एट्रीब्यूट्स का विश्लेषण करके JSON/YAML स्पेसिफिकेशन फ़ाइल बनाती है।
• इंटरैक्टिव Swagger UI — एक वेब इंटरफ़ेस जहां आप एंडपॉइंट्स देख सकते हैं, रिक्वेस्ट भेज सकते हैं और रिस्पॉन्स देख सकते हैं।
• XML कमेंट्स का सपोर्ट — यदि आप अपने कंट्रोलर और मॉडल में XML डॉक्यूमेंटेशन जोड़ते हैं, तो Swagger उसे इंटरफ़ेस में दिखाएगा।
• वर्ज़न के अनुसार ग्रुपिंग — API के विभिन्न वर्ज़न के लिए दस्तावेज़ीकरण के कई वर्ज़न बना सकते हैं।
• कस्टमाइज़ेशन — लुक एंड फील को कस्टमाइज़ करना, हेडर, ऑथेंटिकेशन स्कीम (JWT, Basic Auth) और बहुत कुछ जोड़ना संभव है।

दस्तावेज़ीकरण के लिए XML कमेंट्स जोड़ना

अपने दस्तावेज़ीकरण को जानकारीपूर्ण बनाने के लिए XML कमेंट्स का उपयोग करें। पहले प्रोजेक्ट में XML फ़ाइल जनरेशन चालू करें। .csproj फ़ाइल खोलें और यह जोड़ें:

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

फिर AddSwaggerGen में XML फ़ाइल का पथ बताएं:

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    
    // XML दस्तावेज़ीकरण फ़ाइल का पथ बताएं
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

अब आपके कोड के कमेंट्स Swagger UI में दिखाई देंगे। कमेंट्स के साथ कंट्रोलर का उदाहरण:

/// <summary>
/// यूज़र मैनेजमेंट के लिए कंट्रोलर।
/// </summary>
[ApiController]