कैसे मैंने चिंता करना बंद कर दिया और बाकी एपीआई को मेटाडेटा देना शुरू कर दिया

यदि आप एक सार्वजनिक एपीआई बना रहे हैं, तो आपको इसके प्रलेखन की समस्या का सामना करने की सबसे अधिक संभावना है। बड़ी कंपनियां डेवलपर्स के लिए विशेष पोर्टल बनाती हैं जहां आप प्रलेखन के बारे में पढ़ सकते हैं और चर्चा कर सकते हैं, या अपनी पसंदीदा प्रोग्रामिंग भाषा के लिए क्लाइंट लाइब्रेरी डाउनलोड कर सकते हैं।

इस तरह के एक संसाधन के लिए समर्थन (विशेषकर परिस्थितियों में जब एपीआई सक्रिय रूप से विकसित हो रहा है) एक श्रम-आधारित मामला है। परिवर्तनों के साथ, आपको वास्तविक कार्यान्वयन के साथ प्रलेखन को सिंक्रनाइज़ करना होगा और यह कष्टप्रद है। सिंक्रनाइज़ेशन में निम्न शामिल हैं:

• जाँचता है कि सभी मौजूदा कार्यक्षमता प्रलेखन में वर्णित है
• जाँचता है कि वर्णित सब कुछ काम करता है जैसा कि प्रलेखन में कहा गया है

स्टार्टअप apiary.io के लोग दूसरे बिंदु को स्वचालित करने की पेशकश करते हैं, वे एक विशेष डोमेन-विशिष्ट भाषा (डीएसएल) में प्रलेखन लिखने का अवसर प्रदान करते हैं, और फिर, आपके एपीआई के लिए एक प्रॉक्सी का उपयोग करके, रिकॉर्ड अनुरोध, और समय-समय पर जांचते हैं कि वर्णित सब कुछ सच है। लेकिन इस मामले में, आपको अभी भी सभी दस्तावेज स्वयं लिखना होगा, और यह बहुत ही अच्छा लगता है, क्योंकि आप सबसे पहले कोड में इंटरफ़ेस का वर्णन करते हैं।

बेशक, कोड से अनुरोधों और प्रतिक्रियाओं के विवरण के रूप में एक इंटरफ़ेस निकालने का कोई सार्वभौमिक तरीका नहीं है, लेकिन यदि आप एक रूपरेखा का उपयोग करते हैं जिसमें मार्ग और क्वेरी निष्पादन के संबंध में समझौते हैं, तो ऐसी जानकारी प्राप्त की जा सकती है। इसके अलावा, एक राय है कि इस तरह का विवरण आवश्यक नहीं है और क्लाइंट को स्वयं समझना होगा कि REST API के साथ कैसे काम किया जाए, केवल रूट संसाधन और उपयोग किए गए मीडिया प्रकारों के URL को जानते हुए। लेकिन मैंने एक भी गंभीर सार्वजनिक एपीआई नहीं देखा है जो इस दृष्टिकोण का उपयोग करता है।

स्वचालित रूप से प्रलेखन उत्पन्न करने के लिए, आपको मेटाडेटा का वर्णन करने के लिए एक प्रारूप की आवश्यकता होगी, डब्ल्यूएसडीएल जैसी कुछ, लेकिन रीस्ट के संदर्भ में विवरण के साथ।

कई विकल्प हैं:

• WADL - वर्णन के लिए XML के उपयोग की आवश्यकता है, और यह लंबे समय तक फैशनेबल नहीं रहा है।
• स्वैगर की युक्ति - स्वैगर फ्रेमवर्क में प्रयुक्त मेटाडेटा प्रारूप, जोसन के आधार पर, कई फ्रेमवर्क के लिए जनरेटर हैं और मेटाडेटा पर प्रलेखन प्रकाशित करने के लिए एक आवेदन है।
• Google API खोज दस्तावेज़ - एक मेटाडेटा प्रारूप जो Google अपनी कुछ सेवाओं के लिए उपयोग करता है।
• I \ O डॉक्स Google के समान एक और प्रारूप है।
• खुद का प्रारूप।

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

कार्यान्वयन

आगे यह उन लोगों के लिए दिलचस्प नहीं होगा जो ASP.NET WebAPI से दूर हैं। तो, आपके पास इस प्लेटफ़ॉर्म पर एक एपीआई है और आप मेटाडेटा प्रकाशित करना चाहते हैं। सबसे पहले, हमें एक विशेषता की आवश्यकता है जो क्रियाओं और प्रकारों को चिह्नित करेगी जिनके विवरण मेटाडेटा में गिरेंगे:

[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class, AllowMultiple = false)] public class MetaAttribute : Attribute { } 

अब एक कंट्रोलर बनाते हैं जो टाइप स्कीमों को लौटाएगा (कुछ ऐसा है जैसे कि json स्कीमा , लेकिन सिंपल), जो कि एपीआई में उपलब्ध हैं:

  public class TypeMetadataController : ApiController { private readonly Assembly typeAssembly; public TypeMetadataController(Assembly typeAssembly) { this.typeAssembly = typeAssembly; } [OutputCache] public IEnumerable<ApiType> Get() { return this.typeAssembly .GetTypes() .Where(t => Attribute.IsDefined(t, typeof(MetaAttribute))) .Select(GetApiType); } [OutputCache] public ApiType Get(String name) { var type = this.Get().FirstOrDefault(t => t.Name == name); if (type == null) throw new ResourceNotFoundException<ApiType, String>(name); return type; } ApiType GetApiType(Type type) { var dataContractAttribute = type.GetCustomAttribute<DataContractAttribute>(); return new ApiType { Name = dataContractAttribute != null ? dataContractAttribute.Name : type.Name, DocumentationArticleId = dataContractAttribute != null ? dataContractAttribute.Name : type.Name, Properties = type.GetMembers() .Where(p => p.IsDefined(typeof(DataMemberAttribute), false)) .Select(p => { var dataMemberAttribute = p.GetCustomAttributes(typeof (DataMemberAttribute), false).First() as DataMemberAttribute; return new ApiTypeProperty { Name = dataMemberAttribute != null ? dataMemberAttribute.Name : p.Name, Type = ApiType.GetTypeName(GetMemberUnderlyingType(p)), DocumentationArticleId = String.Format("{0}.{1}", dataContractAttribute != null ? dataContractAttribute.Name : type.Name, dataMemberAttribute != null ? dataMemberAttribute.Name : p.Name) }; } ).ToList() }; } static Type GetMemberUnderlyingType(MemberInfo member) { switch (member.MemberType) { case MemberTypes.Field: return ((FieldInfo)member).FieldType; case MemberTypes.Property: return ((PropertyInfo)member).PropertyType; default: throw new ArgumentException("MemberInfo must be if type FieldInfo or PropertyInfo", "member"); } } } 

यह बहुत संभावना नहीं है कि प्रकार रनटाइम में बदल जाएंगे, इसलिए हम परिणाम को कैश करते हैं।
API द्वारा हैंडल किए जाने वाले अनुरोधों के बारे में जानकारी प्राप्त करने के लिए, आप IApiExplorer का उपयोग कर सकते हैं।

  public class ResourceMetadataController : ApiController { private readonly IApiExplorer apiExplorer; public ResourceMetadataController(IApiExplorer apiExplorer) { this.apiExplorer = apiExplorer; } [OutputCache] public IEnumerable<ApiResource> Get() { var controllers = this.apiExplorer .ApiDescriptions .Where(x => x.ActionDescriptor.ControllerDescriptor.GetCustomAttributes<MetaAttribute>().Any() || x.ActionDescriptor.GetCustomAttributes<MetaAttribute>().Any()) .GroupBy(x => x.ActionDescriptor.ControllerDescriptor.ControllerName) .Select(x => x.First().ActionDescriptor.ControllerDescriptor.ControllerName) .ToList(); return controllers.Select(GetApiResourceMetadata).ToList(); } ApiResource GetApiResourceMetadata(string controller) { var apis = this.apiExplorer .ApiDescriptions .Where(x => x.ActionDescriptor.ControllerDescriptor.ControllerName == controller && ( x.ActionDescriptor.GetCustomAttributes<MetaAttribute>().Any() || x.ActionDescriptor.ControllerDescriptor.GetCustomAttributes<MetaAttribute>().Any() ) ).GroupBy(x => x.ActionDescriptor); return new ApiResource { Name = controller, Requests = apis.Select(g => this.GetApiRequest(g.First(), g.Select(d => d.RelativePath))).ToList(), DocumentationArticleId = controller }; } ApiRequest GetApiRequest(ApiDescription api, IEnumerable<String> uris) { return new ApiRequest { Name = api.ActionDescriptor.ActionName, Uris = uris.ToArray(), DocumentationArticleId = String.Format("{0}.{1}", api.ActionDescriptor.ControllerDescriptor.ControllerName, api.ActionDescriptor.ActionName), Method = api.HttpMethod.Method, Parameters = api.ParameterDescriptions.Select( parameter => new ApiRequestParameter { Name = parameter.Name, DocumentationArticleId = String.Format("{0}.{1}.{2}", api.ActionDescriptor.ControllerDescriptor.ControllerName, api.ActionDescriptor.ActionName, parameter.Name), Source = parameter.Source.ToString().ToLower().Replace("from",""), Type = ApiType.GetTypeName(parameter.ParameterDescriptor.ParameterType) }).ToList(), ResponseType = ApiType.GetTypeName(api.ActionDescriptor.ReturnType), RequiresAuthorization = api.ActionDescriptor.GetCustomAttributes<RequiresAuthorization>().Any() }; } } 

सभी लौटाए गए ऑब्जेक्ट्स में एक फ़ील्ड है `DocumentationArticleId` - यह मेटाडेटा से अलग से संग्रहीत किए गए तत्वों के लिए प्रलेखन लेख का पहचानकर्ता है, उदाहरण के लिए, एक json फ़ाइल या डेटाबेस में।

अब वह सब कुछ है जो प्रलेखन को दिखाने और संपादित करने के लिए एक-पेज का आवेदन करना है:



बाकी कोड GitHub पर उपलब्ध है ।