वेबएपीआई: ऑटो जनरेट रीस्ट एपीआई वेब डॉक्यूमेंटेशन

इस ब्लॉग पोस्ट में, हम ApiExplorer पर एक नज़दीकी नज़र डालेंगे, जो कि IApiExplorer का डिफ़ॉल्ट कार्यान्वयन है, और देखें कि आप सुलभ REST API का उपयोग करके वेब दस्तावेज़ कैसे जल्दी से तैयार कर सकते हैं। इस दस्तावेज़ में विभिन्न प्रकार की जानकारी होगी, उदाहरण के लिए, मान्य URL, मान्य HTTP तरीके और अनुरोधों के लिए अपेक्षित पैरामीटर। आपकी REST सेवा के लिए इस तरह की जानकारी तृतीय-पक्ष डेवलपर्स को आपके API का उपभोग करने की अनुमति देगी, ताकि यह जान सके कि इसके पुर्ज़ों को सही ढंग से कैसे कॉल किया जाए। संभवतः वेब दस्तावेज़ीकरण के इस पृष्ठ के बारे में सबसे अच्छी बात यह है कि यह आपके REST API के अद्यतन के साथ स्वचालित रूप से अपडेट हो जाएगा।

ApiExplorer

इस वर्ग का मुख्य उद्देश्य ApiDescription तत्वों का एक संग्रह उत्पन्न करना है। यह स्थैतिक मार्ग की जाँच और आपके नियंत्रकों के अंदर उपलब्ध क्रियाओं द्वारा किया जाता है। प्रत्येक ApiDescription तत्व आपकी सेवा के माध्यम से उपलब्ध API का वर्णन करता है। जैसा कि आप सरलीकृत आरेख (चित्र 1) में देख सकते हैं अपीस्क्रिप्शन में बुनियादी जानकारी जैसे कि HttpMethod, RelativePath, प्रलेखन, आदि शामिल हैं। लेकिन इसके अलावा, इसमें ApiDescriptor तत्व शामिल है, जो WebAPI कोर का हिस्सा है जो संबंधित कार्रवाई के बारे में सब कुछ जानता है। आप इस तत्व का उपयोग व्यापक जानकारी जैसे कि एक्शन नाम, रिटर्न प्रकार, उपयोगकर्ता विशेषताओं आदि का उपयोग करने के लिए कर सकते हैं। इसी तरह, आप इस API के अपेक्षित मापदंडों की जांच करने के लिए ParameterDescriptor तत्व का उपयोग कर सकते हैं।


चित्र 1। ApiDescription वर्ग आरेख

आइए देखें कि हम एक सहायता पृष्ठ कैसे बना सकते हैं।

एपीआई सहायता पेज जनरेशन

सादगी के लिए, मैं मान लूंगा कि हम ASP.NET MVC के साथ अपनी REST सेवा का उपयोग करते हैं। आप अन्य कार्यान्वयन अनुभागों में अन्य कार्यान्वयन विचारों को नीचे देख सकते हैं।

उदाहरण

उदाहरण के लिए, मैं मानक "वेब एपीआई" टेम्पलेट का उपयोग करता हूं।


अंजीर। २। वेब एपीआई परियोजना चयन

डिफ़ॉल्ट रूप से, इस टेम्पलेट में HomeController MVC नियंत्रक और ValuesController वेब एपीआई शामिल हैं। आइए हमारे सहायता पृष्ठ को प्रदर्शित करने के लिए होमकंट्रोलर में सूचकांक क्रिया को बदलें।

चरण 1। देखें में ApiExplorer का उपयोग करना

अनुक्रमणिका क्रिया में कोड की निम्नलिखित दो पंक्तियाँ जोड़ें:

public ActionResult Index() { var apiExplorer = GlobalConfiguration.Configuration.Services.GetApiExplorer(); return View(apiExplorer); } 

चरण 2. एपीआई प्रदर्शित करने के लिए दृश्य सेट करें

Index.cshtml में हम IApiExplorer मॉडल प्रकार निर्दिष्ट कर सकते हैं:

@model System.Web.Http.Description.IApiExplorer

फिर हम समर्थित HTTP विधियों, सापेक्ष URL, क्रियाओं का विवरण और अपेक्षित पैरामीटर प्रदर्शित करने के लिए Model.ApiDeslass के सभी तत्वों के माध्यम से जा सकते हैं।

 @foreach (var api in Model.ApiDescriptions) { <li> <h5>@api.HttpMethod @api.RelativePath</h5> <blockquote> <p>@api.Documentation</p> @if (api.ParameterDescriptions.Count > 0) { <h6>Parameters</h6> <ul> @foreach (var parameter in api.ParameterDescriptions) { <li>@parameter.Name: @parameter.Documentation (@parameter.Source)</li> } </ul> } </blockquote> </li> } 

बेशक आप अपने HTML मार्कअप को अपनी इच्छानुसार कस्टमाइज़ कर सकते हैं। प्रस्तुति के लिए नीचे पूरा कोड है:

 @model System.Web.Http.Description.IApiExplorer <div id="body"> <section class="featured"> <div class="content-wrapper"> <hgroup class="title"> <h1>ASP.NET Web API Help Page</h1> </hgroup> </div> </section> <section class="content-wrapper main-content clear-fix"> <h3>APIs</h3> <ul> @foreach (var api in Model.ApiDescriptions) { <li> <h5>@api.HttpMethod @api.RelativePath</h5> <blockquote> <p>@api.Documentation</p> @if (api.ParameterDescriptions.Count > 0) { <h6>Parameters</h6> <ul> @foreach (var parameter in api.ParameterDescriptions) { <li>@parameter.Name: @parameter.Documentation (@parameter.Source)</li> } </ul> } </blockquote> </li> } </ul> </section> </div> 

अब, आवेदन शुरू करने के बाद, आपको उपलब्ध REST API (चित्र 3) के विवरण के साथ अगला पृष्ठ देखना चाहिए।


चित्र 3। वेब डॉक्यूमेंटेशन पेज

यदि आप एक करीब से देखते हैं, तो एपीआई विवरण केवल "XYZ के लिए प्रलेखन" कहता है, जो स्वाभाविक रूप से बहुत उपयोगी नहीं है। आइए कुछ उपयोगी जानकारी जोड़ें।

चरण 3. प्रलेखन जोड़ना

एपीआई के लिए दस्तावेज तैयार करते समय, हमारा ApiExplorer आवश्यक जानकारी प्रदान करने के लिए एक IDocumentationProvider का अनुरोध करता है। IDocumentationProvider एक अमूर्त तंत्र है जो आपको API क्रियाओं के दस्तावेजीकरण के लिए जानकारी प्राप्त करने के लिए अपने तरीके को परिभाषित करने की अनुमति देता है। यह आपको अपने खुद के IDocumentationProvider को लागू करने की अनुमति देता है, जो आपके लिए आवश्यक स्रोत से जानकारी निकाल देगा। नीचे आप IDocumentationProvider का एक उदाहरण कार्यान्वयन पा सकते हैं जो C # दस्तावेजी टिप्पणियों से जानकारी निकालता है।

 public class XmlCommentDocumentationProvider : IDocumentationProvider { XPathNavigator _documentNavigator; private const string _methodExpression = "/doc/members/member[@name='M:{0}']"; private static Regex nullableTypeNameRegex = new Regex(@"(.*\.Nullable)" + Regex.Escape("`1[[") + "([^,]*),.*"); public XmlCommentDocumentationProvider(string documentPath) { XPathDocument xpath = new XPathDocument(documentPath); _documentNavigator = xpath.CreateNavigator(); } public virtual string GetDocumentation(HttpParameterDescriptor parameterDescriptor) { ReflectedHttpParameterDescriptor reflectedParameterDescriptor = parameterDescriptor as ReflectedHttpParameterDescriptor; if (reflectedParameterDescriptor != null) { XPathNavigator memberNode = GetMemberNode(reflectedParameterDescriptor.ActionDescriptor); if (memberNode != null) { string parameterName = reflectedParameterDescriptor.ParameterInfo.Name; XPathNavigator parameterNode = memberNode.SelectSingleNode(string.Format("param[@name='{0}']", parameterName)); if (parameterNode != null) { return parameterNode.Value.Trim(); } } } return "No Documentation Found."; } public virtual string GetDocumentation(HttpActionDescriptor actionDescriptor) { XPathNavigator memberNode = GetMemberNode(actionDescriptor); if (memberNode != null) { XPathNavigator summaryNode = memberNode.SelectSingleNode("summary"); if (summaryNode != null) { return summaryNode.Value.Trim(); } } return "No Documentation Found."; } private XPathNavigator GetMemberNode(HttpActionDescriptor actionDescriptor) { ReflectedHttpActionDescriptor reflectedActionDescriptor = actionDescriptor as ReflectedHttpActionDescriptor; if (reflectedActionDescriptor != null) { string selectExpression = string.Format(_methodExpression, GetMemberName(reflectedActionDescriptor.MethodInfo)); XPathNavigator node = _documentNavigator.SelectSingleNode(selectExpression); if (node != null) { return node; } } return null; } private static string GetMemberName(MethodInfo method) { string name = string.Format("{0}.{1}", method.DeclaringType.FullName, method.Name); var parameters = method.GetParameters(); if (parameters.Length != 0) { string[] parameterTypeNames = parameters.Select(param => ProcessTypeName(param.ParameterType.FullName)).ToArray(); name += string.Format("({0})", string.Join(",", parameterTypeNames)); } return name; } private static string ProcessTypeName(string typeName) { //handle nullable var result = nullableTypeNameRegex.Match(typeName); if (result.Success) { return string.Format("{0}{{{1}}}", result.Groups[1].Value, result.Groups[2].Value); } return typeName; } } 

उसके बाद, आपको अपना खुद का IDocumentationProvider कनेक्ट करना होगा। ऐसा करने का सबसे आसान तरीका HttpConfiguration के माध्यम से है। ध्यान दें कि XmlCommentDocumentationProvider को यह जानना होगा कि टिप्पणियों के साथ XML फ़ाइल कहाँ स्थित है।

 var config = GlobalConfiguration.Configuration; config.Services.Replace(typeof(IDocumentationProvider), new XmlCommentDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/MyApp.xml"))); 

आप यह सुनिश्चित कर सकते हैं कि आपकी XML प्रलेखन फ़ाइल की पीढ़ी परियोजना सेटिंग्स (चित्र 4) में शामिल है।


चित्र 4। प्रलेखन फ़ाइल पीढ़ी विकल्प की स्थापना

उसके बाद, सुनिश्चित करें कि आपके कोड में दस्तावेज़ टिप्पणियाँ हैं:



अंत में, अपनी परियोजना को फिर से चलाएं और सुनिश्चित करें कि आपके कोड से प्रलेखन अब आपके REST API (चित्र 5) के वेब प्रलेखन पृष्ठ पर उपलब्ध है।


चित्र 5। विधि प्रलेखन वेब पेज

प्रलेखन से नियंत्रक / कार्रवाई अपवाद

किसी कारण से, एपीआई प्रलेखन पीढ़ी से नियंत्रक या कार्रवाई को बाहर करना आवश्यक हो सकता है। ऐसा करने के लिए, आप विशेष ApiExplorerSettingsAttribute विशेषता का उपयोग कर सकते हैं:

 public class ValuesController : ApiController { [ApiExplorerSettings(IgnoreApi = true)] public void MySpecialAction() { } } 

यह नियंत्रक के लिए इस्तेमाल किया जा सकता है:

 [ApiExplorerSettings(IgnoreApi = true)] public class MySpecialController : ApiController { 

अन्य कार्यान्वयन

मैंने ऊपर जो दिखाया वह वेब प्रलेखन पृष्ठ को लागू करने का सिर्फ एक तरीका है। लेकिन कई अन्य तरीके हो सकते हैं, यहां, उदाहरण के लिए, एक और विचार:

• अपना स्वयं का ApiController कार्यान्वयन (उदा। HelpController) बनाएं। कंट्रोलर के अंदर, आपके पास एक GET एक्शन होगा जो एपीआई (जो भी प्रारूप आपको पसंद है) के बारे में जानकारी देता है। अंदर, HelpController ApiExplorer और इसके माध्यम से उपलब्ध सभी जानकारी का उपयोग करेगा। इस दृष्टिकोण का लाभ यह है कि यह स्वयं-होस्ट मोड में और वेब सेवा के रूप में काम करेगा।

अनुवादक का नोट

लेख भविष्य की कार्यक्षमता का वर्णन करता है जो ASP.NET WebAPI में जोड़ा जाएगा। आप WebAPI रिपॉजिटरी aspnetwebstack.codeplex.com/.../353867 से आवश्यक पैकेज इंस्टॉल करके इसे आजमा सकते हैं कि यह एक अलग लेख में कैसे लिखा जा सकता है।