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

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

REST API का दस्तावेज़ीकरण C# (.NET) में आधुनिक विकास का एक अनिवार्य हिस्सा है। OpenAPI विनिर्देश (पहले Swagger के नाम से जाना जाता था) आपको एंडपॉइंट, डेटा मॉडल, पैरामीटर और प्रतिक्रियाओं को एक एकल, मशीन-पठनीय प्रारूप (JSON/YAML) में वर्णित करने की अनुमति देता है। .NET Core / .NET 5+ इकोसिस्टम में, OpenAPI विनिर्देश के स्वचालित जनरेशन के लिए दो मुख्य उपकरण हैं: Swashbuckle.AspNetCore और NSwag। दोनों उपकरण ASP.NET Core में एकीकृत होते हैं, आपके कोड का विश्लेषण करते हैं और इंटरैक्टिव दस्तावेज़ीकरण (Swagger UI) बनाते हैं।

Swashbuckle.AspNetCore: क्लासिक विकल्प

Swashbuckle .NET में Swagger/OpenAPI जनरेशन के लिए सबसे लोकप्रिय पैकेज है। यह कंट्रोलर, रूटिंग एट्रीब्यूट और मॉडल एनोटेशन के आधार पर स्वचालित रूप से विनिर्देश बनाता है। यह OpenAPI 3.0 और Swagger 2.0 को सपोर्ट करता है।

स्थापना और बुनियादी कॉन्फ़िगरेशन

dotnet add package Swashbuckle.AspNetCore

Program.cs (या पुराने संस्करणों के लिए Startup.cs) फ़ाइल में, सेवाएँ और middleware जोड़ें:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();builder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen(c =>{    c.SwaggerDoc("v1", new OpenApiInfo    {        Title = "मेरा API",        Version = "v1",        Description = "शैक्षिक साइट के लिए उदाहरण API"    });});

var app = builder.Build();

if (app.Environment.IsDevelopment()){    app.UseSwagger();    app.UseSwaggerUI(c =>    {        c.SwaggerEndpoint("/swagger/v1/swagger.json", "मेरा API v1");    });}

app.MapControllers();app.Run();

रन करने के बाद, /swagger पते पर जाएँ - एक इंटरैक्टिव UI खुलेगा जहाँ आप सीधे ब्राउज़र से एंडपॉइंट का परीक्षण कर सकते हैं।

XML टिप्पणियाँ जोड़ना

दस्तावेज़ीकरण में XML टिप्पणियों से विवरण शामिल करने के लिए, .csproj में XML जनरेशन सक्षम करें:

<PropertyGroup>  <GenerateDocumentationFile>true</GenerateDocumentationFile></PropertyGroup>

फिर AddSwaggerGen में XML फ़ाइल का पथ निर्दिष्ट करें:

builder.Services.AddSwaggerGen(c =>{    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);    c.IncludeXmlComments(xmlPath);});

अब कोड की टिप्पणियाँ Swagger UI में प्रदर्शित होंगी।

एनोटेशन के साथ कंट्रोलर का उदाहरण

[ApiController][Route("api/[controller]")]public class ProductsController : ControllerBase{    /// <summary>    /// सभी उत्पादों की सूची प्राप्त करें    /// </summary>    [HttpGet]    public ActionResult<IEnumerable<Product>> GetAll()    {        return Ok(new List<Product>());    }

    /// <summary>    /// ID द्वारा उत्पाद प्राप्त करें    /// </summary>    /// <param name="id">उत्पाद का पहचानकर्ता</param>    [HttpGet("{id}")]    public ActionResult<Product> GetById(int id)    {        return Ok(new Product { Id = id, Name = "उदाहरण" });    }}

NSwag: क्लाइंट जनरेशन के साथ बहुमुखी उपकरण

NSwag एक अधिक शक्तिशाली विकल्प है। दस्तावेज़ीकरण जनरेशन के अलावा, यह API के लिए C# क्लाइंट, TypeScript क्लाइंट बना सकता है, और बाहरी OpenAPI विनिर्देशों के आधार पर कोड भी जनरेट कर सकता है।

स्थापना और कॉन्फ़िगरेशन

dotnet add package NSwag.AspNetCore

Program.cs में कॉन्फ़िगरेशन:

builder.Services.AddOpenApiDocument(config =>{    config.Title = "मेरा API (NSwag)";    config.Version = "v1";    config.Description = "NSwag के साथ जनरेट किया गया API";});

// ...