वेब एपि के लिए एक्सएमएल डॉक्यूमेंटेशन में मुख्य परियोजना से परे के दस्तावेज कैसे शामिल हो सकते हैं?

Question

प्रलेखन अपने वेब एपीआई परियोजनाओं में xmlDoc एकीकरण को सक्षम करने के लिए केवल संभाल स्थितियों में, जहां अपने एपीआई प्रकार के सभी अपने WebAPI परियोजना का हिस्सा हैं प्रतीत होता है। विशेष रूप से, यह चर्चा करता है कि एक्सएमएल प्रलेखन को कैसे फिर से जोड़ना है App_Data/XmlDocument.xmlऔर आपके कॉन्फ़िगरेशन में एक लाइन को अनइंस्टॉल करना है जो उस फ़ाइल का उपभोग करेगा। यह स्पष्ट रूप से केवल एक परियोजना के प्रलेखन फ़ाइल के लिए अनुमति देता है।

हालाँकि, मेरे सेटअप में मेरे अनुरोध और प्रतिक्रिया प्रकार एक सामान्य "मॉडल" परियोजना में परिभाषित हैं। इसका मतलब है कि अगर मेरे पास एक समापन बिंदु परिभाषित है जैसे:

[Route("auth/openid/login")]
public async Task<AuthenticationResponse> Login(OpenIdLoginRequest request) { ... }

जहाँ OpenIdLoginRequestएक अलग सी # परियोजना में परिभाषित किया गया है जैसे:

public class OpenIdLoginRequest
{
    /// <summary>
    /// Represents the OpenId provider that authenticated the user. (i.e. Facebook, Google, etc.)
    /// </summary>
    [Required]
    public string Provider { get; set; }

    ...
}

XML डॉक्यूमेंट्स के बावजूद, requestजब आप समापन बिंदु-विशिष्ट मदद पृष्ठ (यानी http://localhost/Help/Api/POST-auth-openid-login) देखते हैं, तो पैरामीटर के गुणों में कोई दस्तावेज़ नहीं होता है ।

मैं इसे कैसे बना सकता हूं ताकि XML एपीआई के साथ सबप्रोजेक्ट्स के प्रकार वेब एपीआई एक्सएमएल प्रलेखन में सामने आए?

Answer 1

इसे प्राप्त करने का कोई अंतर्निहित तरीका नहीं है। हालाँकि, इसके लिए केवल कुछ चरणों की आवश्यकता है:

1. अपने वेब API प्रोजेक्ट के लिए XML प्रलेखन को अपने सबप्रोजेक्ट (प्रोजेक्ट प्रॉपर्टीज / बिल्ड से) के लिए सक्षम करें। इस समय को छोड़कर, इसे सीधे रूट करें XmlDocument.xmlताकि यह आपके प्रोजेक्ट के रूट फ़ोल्डर में उत्पन्न हो।

2. अपने में इस एक्सएमएल फ़ाइल कॉपी करने के लिए अपने वेब एपीआई परियोजना की postbuild ईवेंट संशोधित करें App_Dataफ़ोल्डर:

   copy "$(SolutionDir)SubProject\XmlDocument.xml" "$(ProjectDir)\App_Data\Subproject.xml"

   जहाँ Subproject.xmlआपके प्रोजेक्ट का नाम प्लस है, उसका नाम बदला जाना चाहिए .xml।

3. अगला खोलें Areas\HelpPage\App_Start\HelpPageConfigऔर निम्न पंक्ति खोजें:

   config.SetDocumentationProvider(new XmlDocumentationProvider(
       HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

   यह वह लाइन है जिसे आपने शुरुआत में XML मदद प्रलेखन को सक्षम करने के लिए शुरू में असहज किया था। उस पंक्ति को इसके साथ बदलें:

   config.SetDocumentationProvider(new XmlDocumentationProvider(
       HttpContext.Current.Server.MapPath("~/App_Data")));

   यह चरण सुनिश्चित करता है कि XmlDocumentationProviderवह निर्देशिका पारित हो, जिसमें आपकी XML फाइलें हों, बजाय आपकी परियोजना के विशिष्ट XML फ़ाइल के।

4. अंत Areas\HelpPage\XmlDocumentationProviderमें, निम्नलिखित तरीकों से संशोधित करें :

   ए। _documentNavigatorफ़ील्ड को इसके साथ बदलें :

   private List<XPathNavigator> _documentNavigators = new List<XPathNavigator>();

   ख। निर्माता को इसके साथ बदलें:

   public XmlDocumentationProvider(string appDataPath)
   {
       if (appDataPath == null)
       {
           throw new ArgumentNullException("appDataPath");
       }
   
       var files = new[] { "XmlDocument.xml", "Subproject.xml" };
       foreach (var file in files)
       {
           XPathDocument xpath = new XPathDocument(Path.Combine(appDataPath, file));
           _documentNavigators.Add(xpath.CreateNavigator());
       }
   }

   सी। निर्माता के नीचे निम्न विधि जोड़ें:

   private XPathNavigator SelectSingleNode(string selectExpression)
   {
       foreach (var navigator in _documentNavigators)
       {
           var propertyNode = navigator.SelectSingleNode(selectExpression);
           if (propertyNode != null)
               return propertyNode;
       }
       return null;
   }

   घ। और अंत में, सभी संकलक त्रुटियों को ठीक करें (तीन होना चाहिए) जिसके परिणामस्वरूप संदर्भ को _documentNavigator.SelectSingleNodeहटा दिया गया है और _documentNavigator.इसे हटा दिया गया है ताकि यह अब SelectSingleNodeऊपर बताई गई नई विधि को कॉल करे ।

यह अंतिम चरण वह है जो दस्तावेज़ प्रदाता को केवल प्राथमिक परियोजना के बजाय सहायता पाठ के लिए कई XML दस्तावेज़ों को देखने का समर्थन करता है।

अब जब आप अपने हेल्प डॉक्यूमेंटेशन की जांच करते हैं, तो यह आपके संबंधित प्रोजेक्ट में टाइप से एक्सएमएल डॉक्यूमेंट शामिल करेगा।

Comments

बहुत बढ़िया जवाब। मुझे वास्तव में लगता है कि कंस्ट्रक्टर के लिए स्ट्रिंग्स की एक सरणी को स्वीकार करना आसान है: सार्वजनिक XmlDocumentationProvider (स्ट्रिंग appDataPath) और इस सूची को डॉक्यूमेंटेशन प्रोवाइडर में एन्यूमरेट करें।

— कप्तान जॉन

शानदार, यह वही था जिसकी मुझे तलाश थी !! यदि आप (मेरे जैसे) के var files...साथ लाइन की जगह का सुझाव देते हैं, var files = Directory.GetFiles(documentPath, "*.xml");तो हमेशा उन xml दस्तावेज़ीकरण फ़ाइलों के नाम / संख्या पता नहीं चलेगी जो वहां होंगी। आवश्यकतानुसार फ़्यूचर फ़िल्टरिंग भी कर सकता है।

— s

@ लिंड्रो, उत्तर को बेहतर बनाने के लिए धन्यवाद! :) खुशी है कि आप इसे मददगार पाया।

— कर्क वल

अगर मैं आपको इस विस्तृत और सही उत्तर के लिए +10 दे सकता था

— मार्क वैन स्ट्रेटेन

मैं यहां कुछ अन्य लोगों के साथ अपने संशोधन जोड़ना चाहूंगा। मैंने रूट प्रोजेक्ट App_Data \ प्रलेखन फ़ोल्डर में बनाई गई xml फ़ाइल के लिए ... \ नोटेशन का उपयोग किया था। मैंने तब उस निर्देशिका से सभी xml फ़ाइलों को पेलने की @ विधि का उपयोग किया। यह खूबसूरती से काम करता है और मुझे आश्चर्य है कि यह सिर्फ यह नहीं है कि यह बॉक्स से बाहर कैसे काम करता है। बहुत धन्यवाद।

— दारूल

Answer 2

मैं इसमें भी भाग गया, लेकिन मैं बाद में समस्याओं से बचने के लिए किसी भी उत्पन्न कोड को संपादित या डुप्लिकेट नहीं करना चाहता था।

अन्य उत्तरों पर निर्माण, यहाँ कई XML स्रोतों के लिए एक स्व-निहित प्रलेखन प्रदाता है। बस इसे अपनी परियोजना में छोड़ दें:

/// <summary>A custom <see cref="IDocumentationProvider"/> that reads the API documentation from a collection of XML documentation files.</summary>
public class MultiXmlDocumentationProvider : IDocumentationProvider, IModelDocumentationProvider
{
    /*********
    ** Properties
    *********/
    /// <summary>The internal documentation providers for specific files.</summary>
    private readonly XmlDocumentationProvider[] Providers;


    /*********
    ** Public methods
    *********/
    /// <summary>Construct an instance.</summary>
    /// <param name="paths">The physical paths to the XML documents.</param>
    public MultiXmlDocumentationProvider(params string[] paths)
    {
        this.Providers = paths.Select(p => new XmlDocumentationProvider(p)).ToArray();
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(MemberInfo subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(Type subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(HttpControllerDescriptor subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(HttpActionDescriptor subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetDocumentation(HttpParameterDescriptor subject)
    {
        return this.GetFirstMatch(p => p.GetDocumentation(subject));
    }

    /// <summary>Gets the documentation for a subject.</summary>
    /// <param name="subject">The subject to document.</param>
    public string GetResponseDocumentation(HttpActionDescriptor subject)
    {
        return this.GetFirstMatch(p => p.GetResponseDocumentation(subject));
    }


    /*********
    ** Private methods
    *********/
    /// <summary>Get the first valid result from the collection of XML documentation providers.</summary>
    /// <param name="expr">The method to invoke.</param>
    private string GetFirstMatch(Func<XmlDocumentationProvider, string> expr)
    {
        return this.Providers
            .Select(expr)
            .FirstOrDefault(p => !String.IsNullOrWhiteSpace(p));
    }
}

... और इसे अपने HelpPageConfigXML दस्तावेज़ों के लिए पथों के साथ सक्षम करें जो आप चाहते हैं:

config.SetDocumentationProvider(new MultiXmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/Api.xml"), HttpContext.Current.Server.MapPath("~/App_Data/Api.Models.xml")));

Comments

यह एक बेहतरीन उपाय है। मैं इसे उन समाधानों पर पसंद करता हूं जिनके लिए डिफ़ॉल्ट हेल्पपेज कक्षाओं के संशोधन की आवश्यकता होती है क्योंकि वे अपडेट पर ओवरराइट किए जाएंगे।

— एरोनानअमरर्स

यह शानदार ढंग से काम करता है, पोस्ट करने के लिए धन्यवाद। इस समय का उपयोग करके किसी को भी बचाने के लिए, आपको अभी भी kirk के स्वीकृत उत्तर के पहले दो चरणों को करने की आवश्यकता है, अर्थात 1) अपने सबप्रोजेक्ट के लिए XML दस्तावेज़ सक्षम करें और 2) इस XML फ़ाइल को कॉपी करने के लिए अपने वेब एपीआई प्रोजेक्ट के पुनर्निर्माण की घटना को संशोधित करें। आपका App_Data फ़ोल्डर।

— टोमरेडॉक्स

और फिर यह रेखा बन जाती है: config.SetDocumentationProvider (नया MultiXmlDocumentationProvider (HttpContext.Current.Server.MapPath) ("~ / App_Data / [जिसे आपने अपना SubProject xml फ़ाइल नाम कहा है] .xml")));

— टोमरेडॉक्स

चरणों का पालन किया, लेकिन काम नहीं किया :(। कोई त्रुटि नहीं है, इसलिए सुनिश्चित करें कि क्या गलत हुआ है। यह अभी भी केवल एपीआई दस्तावेज़ दिखाता है, लेकिन अतिरिक्त परियोजना दस्तावेज़ नहीं। मैंने भी स्वीकृत उत्तर में चरणों की कोशिश की और यह एक ही बात है। कुछ भी विशेष रूप से मुझे जांचना चाहिए?

— stt106

किसी कारण से मैं अभी भी डिफ़ॉल्ट जीईटी एपीआई / मुझे देखता हूं जो वीएस में प्रोजेक्ट शुरू होने के साथ आता है।

— जॉन ज़ब्रोस्की

Answer 3

ऐसा करने का एक और सरल तरीका है xml फ़ाइलों को मर्ज करना। मेरे निम्न उत्तर में उदाहरण कोड:

वेब एपि मदद पेज XML 1 से अधिक फाइलों से टिप्पणी करता है

Answer 4

यहां मैं इसके साथ एक उत्तर लिंक प्रदान करता हूं, जो आपकी मदद कर सकता है। आप आसानी से प्रलेखन के लिए कई XML फ़ाइल का उपयोग कर सकते हैं।

वेब एपि मदद पेज XML 1 से अधिक फाइलों से टिप्पणी करता है

Answer 5

इस समस्या को ठीक करने का सबसे आसान तरीका आपके द्वारा तैनात सर्वर पर App_Code फ़ोल्डर बना रहा है। इसके बाद XmlDocument.xml को अपने बिन फ़ोल्डर में स्थानीय रूप से App_Code फ़ोल्डर में कॉपी करें

Comments

सुझाव के लिए धन्यवाद !! इस तरह के सहायक उत्तर के लिए कोई और -1 नहीं। हां, यदि आप इसे Azure Cloud App Service में परिनियोजित करते हैं, तो कई समस्याएँ कई * .xml परिनियोजन के साथ होती हैं, इसलिए उन्हें स्वैगर के लिए उपलब्ध कराना, उदाहरण के लिए, वास्तव में मुश्किल हो सकता है। लेकिन मैं इसके बजाय एक और मानक ASP.Net सर्वर-साइड फ़ोल्डर, अर्थात् App_GlobalResources चुनेंगे, क्योंकि xmldoc फाइलें संसाधनों के बहुत समान हैं। यह विशेष रूप से सच है क्योंकि मेरे पास अभी भी मेरी परियोजना में App_Code फ़ोल्डर नहीं है और यह कोई फर्क नहीं पड़ता कि कौन सा मानक फ़ोल्डर बनाना है।

— मौद्रिक

निम्न मानक फ़ोल्डर ने मेरे लिए काम किया: App_Code - डिफ़ॉल्ट सेटिंग्स पर क्लाइंट से दिखाई नहीं देता है App_GlobalResources - डिफ़ॉल्ट सेटिंग्स पर क्लाइंट से दिखाई नहीं देता है App_LocalResources - डिफ़ॉल्ट सेटिंग्स पर क्लाइंट से दिखाई नहीं देता है

— moudrick

मुझे प्रत्येक मानक फ़ोल्डर के साथ उन मुद्दों को भी सूचीबद्ध करने दें जो मेरे लिए काम नहीं करते थे। बिन - केवल * .xml मुख्य सभा के लिए App_Data को हटा दिया गया है - सबसे व्यावहारिक सेटिंग क्लाउड पर तैनात करने के लिए इस फ़ोल्डर में सब कुछ छोड़ना है

— moudrick

क्या कोई भी व्यक्ति जो इस उत्तर को संपादित करता है, उपरोक्त सभी विचारों को प्रतिबिंबित करने के लिए, शायद विस्तारित अटकलों के साथ?

— मौद्रिक