C# अकादमी · पाठ

संस्करणित API का दस्तावेज़ीकरण

कई API संस्करणों के लिए दस्तावेज़ उपलब्ध कराएँ।

पाठ 4, कुल 4 में से13 चरण

संस्करणित API का दस्तावेज़ीकरण, CoddyKit पर C# अकादमी का एक निःशुल्क पाठ है। यह 4 में से 4वाँ पाठ है। आप नीचे पूरा पाठ निःशुल्क पढ़ सकते हैं—फिर अंतर्निहित कोड संपादक और 24/7 एआई ट्यूटर के साथ ब्राउज़र में इसका व्यावहारिक अभ्यास कर सकते हैं। यह C# अकादमी सीखने के मार्ग का हिस्सा है और आपकी प्रगति वेब तथा CoddyKit ऐप पर सिंक होती रहती है। C# अकादमी पाठ्यक्रम में कुल 4 पाठ शामिल हैं।

प्रत्येक संस्करण के लिए एक दस्तावेज़

जब किसी एपीआई के कई संस्करण हों, तो आम तौर पर प्रत्येक संस्करण के लिए अलग OpenAPI दस्तावेज़ रखना उपयोगी होता है, ताकि उपभोक्ताओं को केवल उनके लिए प्रासंगिक एंडपॉइंट दिखाई दें।

// /openapi/v1.json -> only v1 endpoints
// /openapi/v2.json -> only v2 endpoints

एपीआई संस्करण विवरण प्रदाता

Asp.Versioning IApiVersionDescriptionProvider उपलब्ध कराता है, जो खोजे गए प्रत्येक एपीआई संस्करण की सूची देता है। प्रत्येक संस्करण के लिए एक दस्तावेज़ पंजीकृत करने हेतु इस सूची पर दोहराव करें।

var provider = app.Services
    .GetRequiredService<IApiVersionDescriptionProvider>();

foreach (var desc in provider.ApiVersionDescriptions)
{
    // desc.GroupName is e.g. "v1", "v2"
}

प्रत्येक संस्करण के लिए दस्तावेज़ पंजीकृत करना

प्रत्येक संस्करण समूह के लिए एक बार AddOpenApi कॉल करें और प्रत्येक दस्तावेज़ का नाम उस समूह के नाम पर रखें।

builder.Services
    .AddApiVersioning()
    .AddApiExplorer(o =>
    {
        o.GroupNameFormat = "'v'VVV";
        o.SubstituteApiVersionInUrl = true;
    });

builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");

एंडपॉइंट को सही दस्तावेज़ में छाँटना

दस्तावेज़ रूपांतरणकर्ता या ShouldInclude शर्त का उपयोग करें, ताकि प्रत्येक दस्तावेज़ में समूह नाम से मिलान किए गए केवल उसी संस्करण के एंडपॉइंट शामिल हों।

builder.Services.AddOpenApi("v1", options =>
{
    options.ShouldInclude = description =>
        description.GroupName == "v1";
});

दस्तावेज़ों का मानचित्रण

डिफ़ॉल्ट पैटर्न के साथ MapOpenApi प्रत्येक नामित दस्तावेज़ को /openapi/{documentName}.json पर उपलब्ध कराता है।

app.MapOpenApi();
// /openapi/v1.json and /openapi/v2.json both available

प्रत्येक दस्तावेज़ की जानकारी सेट करना

रूपांतरणकर्ता में प्रत्येक संस्करण दस्तावेज़ का अपना शीर्षक और संस्करण दें, ताकि दस्तावेज़ अपने बारे में पूरी जानकारी दे सकें।

builder.Services.AddOpenApi("v2", options =>
{
    options.AddDocumentTransformer((doc, ctx, ct) =>
    {
        doc.Info.Title = "Catalog API v2";
        doc.Info.Version = "2.0";
        return Task.CompletedTask;
    });
});

दस्तावेज़ों में अप्रचलित संस्करण चिह्नित करना

यदि कोई संस्करण अप्रचलित है, तो उसके दस्तावेज़ के विवरण में यह बात स्पष्ट करें, ताकि उपयोगकर्ताओं को इंटरफ़ेस में चेतावनी दिखाई दे।

options.AddDocumentTransformer((doc, ctx, ct) =>
{
    if (ctx.DocumentName == "v1")
        doc.Info.Description = "DEPRECATED - migrate to v2.";
    return Task.CompletedTask;
});

यूआरएल में संस्करण बदलना

SubstituteApiVersionInUrl = true दस्तावेज़ में {version:apiVersion} मार्ग टोकन को वास्तविक संस्करण, जैसे v1, से बदल देता है, जिससे मार्ग साफ़ दिखाई देते हैं।

// Without: /api/v{version}/products
// With:    /api/v1/products

प्रत्येक संस्करण के लिए एक इंटरफ़ेस टैब

अधिकांश दर्शक सभी दस्तावेज़ों की एक ड्रॉपडाउन सूची दिखा सकते हैं। इंटरफ़ेस को प्रत्येक संस्करण की JSON फ़ाइल पर निर्देशित करें।

app.MapScalarApiReference(options =>
{
    options.AddDocument("v1", "API v1", "/openapi/v1.json");
    options.AddDocument("v2", "API v2", "/openapi/v2.json");
});

अनुरोध और प्रतिक्रिया के आकार का दस्तावेज़ीकरण

क्योंकि v2 में DTO बदल सकते हैं, इसलिए प्रत्येक संस्करण को अपने DTO प्रकार दें। इसके बाद OpenAPI प्रत्येक दस्तावेज़ में अलग-अलग स्कीमा अपने-आप दिखाता है।

// V1 DTO
public record ProductV1(int Id, string Name);
// V2 DTO (breaking change)
public record ProductV2(int Id, string Title, decimal Price);

सब कुछ एक साथ जोड़ना

पूरी प्रक्रिया यह है: संस्करण-प्रबंधन और एपीआई एक्सप्लोरर को कॉन्फ़िगर करें, छँटाई के साथ प्रत्येक संस्करण के लिए एक OpenApi दस्तावेज़ पंजीकृत करें, उन्हें मानचित्रित करें और अपने इंटरफ़ेस को प्रत्येक दस्तावेज़ पर निर्देशित करें।

builder.Services.AddApiVersioning().AddApiExplorer(o =>
{
    o.GroupNameFormat = "'v'VVV";
    o.SubstituteApiVersionInUrl = true;
});
builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");
// ...
app.MapOpenApi();
app.MapScalarApiReference();

त्वरित जाँच

पुष्टि करें कि संस्करणयुक्त दस्तावेज़ कैसे बनाए जाते हैं।

इंटरैक्टिव पाठ में इसका उत्तर दें

पुनरावलोकन

आपने संस्करणयुक्त एपीआई का दस्तावेज़ीकरण किया:

AddOpenApi("vN") के साथ प्रत्येक संस्करण के लिए एक नामित OpenAPI दस्तावेज़ पंजीकृत करें।
IApiVersionDescriptionProvider संस्करणों की गणना करता है; ShouldInclude एंडपॉइंट को छाँटता है।
SubstituteApiVersionInUrl वास्तविक संस्करणयुक्त मार्ग दिखाता है।
प्रति-संस्करण दृश्य के लिए इंटरफ़ेस को प्रत्येक दस्तावेज़ पर निर्देशित करें।

इससे संस्करण-प्रबंधन और OpenAPI पाठ्यक्रम पूरा होता है।

शुरुआत निःशुल्क

एआई शिक्षक के साथ C# सीखें — निःशुल्क

अपने ब्राउज़र में वास्तविक कोड लिखें और चलाएँ, चौबीसों घंटे एआई शिक्षक से तुरंत सहायता पाएँ, और वेब या ऐप पर वहीं से शुरू करें जहाँ आपने छोड़ा था।

पाठ्यक्रम: 93
पाठ: 346

निःशुल्क सीखना शुरू करें पूरा पाठ्यक्रम देखें

अक्सर पूछे जाने वाले प्रश्न

क्या “संस्करणित API का दस्तावेज़ीकरण” पाठ निःशुल्क है?

हाँ—“संस्करणित API का दस्तावेज़ीकरण” का पूरा पाठ यहाँ वेब पर निःशुल्क पढ़ा जा सकता है। इंटरैक्टिव अभ्यास (अंतर्निहित कोड संपादक और 24/7 एआई ट्यूटर) करने और C# अकादमी पाठ्यक्रम का बाकी हिस्सा अनलॉक करने के लिए CoddyKit PRO लें। C# अकादमी पाठ्यक्रम में कुल 4 पाठ शामिल हैं।

“संस्करणित API का दस्तावेज़ीकरण” में मैं क्या सीखूँगा?

कई API संस्करणों के लिए दस्तावेज़ उपलब्ध कराएँ। आप ब्राउज़र में सीधे चलाए जाने वाले व्यावहारिक कोड के साथ C# अकादमी का अभ्यास करते हैं, और पाठ पूरा करते समय 24/7 एआई ट्यूटर आपके प्रश्नों के उत्तर देता है।

क्या C# अकादमी शुरू करने के लिए मुझे किसी अनुभव की आवश्यकता है?

पहले के अनुभव की आवश्यकता नहीं है। CoddyKit पर C# अकादमी शुरुआती से लेकर उन्नत शिक्षार्थियों तक सभी के लिए व्यवस्थित किया गया है, इसलिए आप यहीं से या शुरुआत से सीखना शुरू कर सकते हैं और अपनी गति से आगे बढ़ सकते हैं। यह 4 में से 4वाँ पाठ है।

“संस्करणित API का दस्तावेज़ीकरण” पाठ पूरा करने में कितना समय लगता है?

CoddyKit का अधिकांश पाठ लगभग 5–10 मिनट में पूरा हो जाता है। हर पाठ छोटा और संवादात्मक है, इसलिए आप लगातार प्रगति करते हैं और वेब या ऐप पर वहीं से सीखना जारी रख सकते हैं जहाँ आपने छोड़ा था।

क्या मैं इस C# अकादमी पाठ में कोड लिख और चला सकता हूँ?

हाँ। हर C# अकादमी पाठ में एक अंतर्निर्मित कोड संपादक शामिल है, जिससे आप सीधे अपने ब्राउज़र में वास्तविक कोड लिख और चला सकते हैं और तुरंत एआई प्रतिक्रिया पा सकते हैं—स्थानीय सेटअप की आवश्यकता नहीं है।

इस पाठ्यक्रम के सभी पाठ

← C# अकादमी पर वापस जाएँ