C#编程之C#WebApi中swagger在线文档输出参数和输入参数显示注释
小标 2018-09-17 来源 : 阅读 14731 评论 0

摘要:本文主要向大家介绍了C#编程之C#WebApi中swagger在线文档输出参数和输入参数显示注释,通过具体的内容向大家展示,希望对大家学习C#编程有所帮助。

本文主要向大家介绍了C#编程之C#WebApi中swagger在线文档输出参数和输入参数显示注释,通过具体的内容向大家展示,希望对大家学习C#编程有所帮助。

 
 
最近开发webapi 时需要生成在线文档,发现文档里面没注释,在网上查找资料都不齐全,或者看起来很难看懂。
花了点时间搞出来了这个,很多都是借鉴网上资料整理的,通俗易懂小白专用。

最终效果如上图所示
1.定义一个SwaggerControllerDescProvider实现ISwaggerProvider接口

using Swashbuckle.Swagger;
using System;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Web;
using System.Xml;

namespace Nop.Web.App_Start
{
    /// 


    /// swagger显示控制器的描述
    /// 


    public class SwaggerControllerDescProvider : ISwaggerProvider
    {
        private readonly ISwaggerProvider _swaggerProvider;
        private static ConcurrentDictionary

 _cache =new ConcurrentDictionary();
        private readonly string _xml;
        /// 
        /// 
        /// 

        /// 
        /// xml文档路径
        public SwaggerControllerDescProvider(ISwaggerProvider swaggerProvider,string xml)
        {
            _swaggerProvider = swaggerProvider;
            _xml = xml;
        }

        public SwaggerDocument GetSwagger(string rootUrl, string apiVersion)
        {

            var cacheKey = string.Format("{0}_{1}", rootUrl, apiVersion);
            SwaggerDocument srcDoc = null;
            //只读取一次
            if (!_cache.TryGetValue(cacheKey, out srcDoc))
            {
                srcDoc = _swaggerProvider.GetSwagger(rootUrl, apiVersion);

                srcDoc.vendorExtensions = new Dictionary { { "ControllerDesc", GetControllerDesc() } };
                _cache.TryAdd(cacheKey, srcDoc);
            }
            return srcDoc;
        }

        /// 
        /// 从API文档中读取控制器描述
        /// 

        /// 所有控制器描述
        public  ConcurrentDictionary GetControllerDesc()
        {
            string xmlpath = _xml;
            ConcurrentDictionary controllerDescDict = new ConcurrentDictionary();
            if (File.Exists(xmlpath))
            {
                XmlDocument xmldoc = new XmlDocument();
                xmldoc.Load(xmlpath);
                string type = string.Empty, path = string.Empty, controllerName = string.Empty;

                string[] arrPath;
                int length = -1, cCount = "Controller".Length;
                XmlNode summaryNode = null;
                foreach (XmlNode node in xmldoc.SelectNodes("//member"))
                {
                    type = node.Attributes["name"].Value;
                    if (type.StartsWith("T:"))
                    {
                        //控制器
                        arrPath = type.Split(‘.‘);
                        length = arrPath.Length;
                        controllerName = arrPath[length - 1];
                        if (controllerName.EndsWith("Controller"))
                        {
                            //获取控制器注释
                            summaryNode = node.SelectSingleNode("summary");
                            string key = controllerName.Remove(controllerName.Length - cCount, cCount);
                            if (summaryNode != null && !string.IsNullOrEmpty(summaryNode.InnerText) && !controllerDescDict.ContainsKey(key))
                            {
                                controllerDescDict.TryAdd(key, summaryNode.InnerText.Trim());
                            }
                        }
                    }
                }
            }
            return controllerDescDict;
        }
    }
}


  
2.定义一个JS文件,做成嵌入资源,这个js文件的功能主要有两个,一个是汉化,另一个就是在界面上显示控制器的描述文字

‘use strict‘;
window.SwaggerTranslator = {
    _words: [],

    translate: function () {
        var $this = this;
        $(‘[data-sw-translate]‘).each(function () {
            $(this).html($this._tryTranslate($(this).html()));
            $(this).val($this._tryTranslate($(this).val()));
            $(this).attr(‘title‘, $this._tryTranslate($(this).attr(‘title‘)));
        });
    },

    setControllerSummary : function () {
        $.ajax({
            type: "get",
            async: true,
            url: $("#input_baseUrl").val(),
            dataType: "json",
            success: function (data) {
                var summaryDict = data.ControllerDesc;
                var id, controllerName, strSummary;
                $("#resources_container .resource").each(function (i, item) {
                    id = $(item).attr("id");
                    if (id) {
                        controllerName = id.substring(9);
                        strSummary = summaryDict[controllerName];
                        if (strSummary) {
                            $(item).children(".heading").children(".options").first().prepend(‘
  • ‘ + strSummary + ‘

  • ‘);


  •                         }


  •                     }


  •                 });


  •             }


  •         });


  •     },


  •     _tryTranslate: function (word) {


  •         return this._words[$.trim(word)] !== undefined ? this._words[$.trim(word)] : word;


  •     },



  •     learn: function (wordsMap) {


  •         this._words = wordsMap;


  •     }


  • };




  • /* jshint quotmark: double */


  • window.SwaggerTranslator.learn({


  •     "Warning: Deprecated": "警告:已过时",


  •     "Implementation Notes": "实现备注",


  •     "Response Class": "响应类",


  •     "Status": "状态",


  •     "Parameters": "参数",


  •     "Parameter": "参数",


  •     "Value": "值",


  •     "Description": "描述",


  •     "Parameter Type": "参数类型",


  •     "Data Type": "数据类型",


  •     "Response Messages": "响应消息",


  •     "HTTP Status Code": "HTTP状态码",


  •     "Reason": "原因",


  •     "Response Model": "响应模型",


  •     "Request URL": "请求URL",


  •     "Response Body": "响应体",


  •     "Response Code": "响应码",


  •     "Response Headers": "响应头",


  •     "Hide Response": "隐藏响应",


  •     "Headers": "头",


  •     "Try it out!": "试一下!",


  •     "Show/Hide": "显示/隐藏",


  •     "List Operations": "显示操作",


  •     "Expand Operations": "展开操作",


  •     "Raw": "原始",


  •     "can‘t parse JSON.  Raw result": "无法解析JSON. 原始结果",


  •     "Model Schema": "模型架构",


  •     "Model": "模型",


  •     "apply": "应用",


  •     "Username": "用户名",


  •     "Password": "密码",


  •     "Terms of service": "服务条款",


  •     "Created by": "创建者",


  •     "See more at": "查看更多:",


  •     "Contact the developer": "联系开发者",


  •     "api version": "api版本",


  •     "Response Content Type": "响应Content Type",


  •     "fetching resource": "正在获取资源",


  •     "fetching resource list": "正在获取资源列表",


  •     "Explore": "浏览",


  •     "Show Swagger Petstore Example Apis": "显示 Swagger Petstore 示例 Apis",


  •     "Can‘t read from server.  It may not have the appropriate access-control-origin settings.": "无法从服务器读取。可能没有正确设置access-control-origin。",


  •     "Please specify the protocol for": "请指定协议:",


  •     "Can‘t read swagger JSON from": "无法读取swagger JSON于",


  •     "Finished Loading Resource Information. Rendering Swagger UI": "已加载资源信息。正在渲染Swagger UI",


  •     "Unable to read api": "无法读取api",


  •     "from path": "从路径",


  •     "server returned": "服务器返回"


  • });


  • $(function () {


  •     window.SwaggerTranslator.translate();


  •     window.SwaggerTranslator.setControllerSummary();


  • });





  • 3.修改App_Start中的SwaggerConfig.cs文件,主要代码有两行


  • c.CustomProvider((defaultProvider) => new SwaggerControllerDescProvider(defaultProvider,xmlFile));


  • .EnableSwaggerUi(c => c.InjectJavaScript(thisAssembly, "Test.WebApi.Scripts.Swagger-Custom.js"));


  • Test.WebApi.Scripts.Swagger-Custom.js 这是我们在第二步中定义的资源文件,资源文件名的命名规则如下:文件所在项目的命名空间.文件径路.文件名


  • 最终代码如下



  • public static void Register()


  •         {


  •            var xmlFile = string.Format("{0}/bin/Test.WebApi.XML", System.AppDomain.CurrentDomain.BaseDirectory);



  •             #region 原生配置


  •             var thisAssembly = typeof(SwaggerConfig).Assembly;



  •             GlobalConfiguration.Configuration


  •                 .EnableSwagger(c =>


  •                     {


  •                         c.IncludeXmlComments(GetXmlCommentsPath("Test.Model"));



  •                         //


  •                         c.SingleApiVersion("v1", "Test.WebApi").Description("content");




  •                         //设置接口描述xml路径地址


  •                         c.IncludeXmlComments(xmlFile);



  •                         //


  •                         c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());



  •                         // Wrap the default SwaggerGenerator with additional behavior (e.g. caching) or provide an


  •                         // alternative implementation for ISwaggerProvider with the CustomProvider option.


  •                         //


  •                         c.CustomProvider((defaultProvider) => new InformationApp.WebApi.App_Start.SwaggerControllerDescProvider(defaultProvider, xmlFile));


  •                         //


  •                         c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());



  •                     })


  •                 .EnableSwaggerUi( c =>


  •                     {


  •                         c.InjectJavaScript(thisAssembly, "Test.WebApi.Areas.SSO.Content.js.Swagger-Custom.js");



  •                     });


  •             #endregion


  •         }



  •         private static string GetXmlCommentsPath(string name)


  •         {


  •             return string.Format("{0}/bin/{1}.XML", System.AppDomain.CurrentDomain.BaseDirectory, name);


  •         }





  • 千万要注意的是


  • c.IncludeXmlComments(GetXmlCommentsPath("Test.Model"));


  • 这里面的参数Test.Model是接口输入输出参数的模型类所在的命名空间名称


  • 并且Test.Model这个类库生成的时候还要设置生成xml出来


本文由职坐标整理并发布,希望对同学们有所帮助。了解更多详情请关注职坐标编程语言C#.NET频道!

本文由 @小标 发布于职坐标。未经许可,禁止转载。
喜欢 | 0 不喜欢 | 3
看完这篇文章有何感觉?已经有3人表态,0%的人喜欢 快给朋友分享吧~
评论(0)
后参与评论

您输入的评论内容中包含违禁敏感词

我知道了

助您圆梦职场 匹配合适岗位
验证码手机号,获得海同独家IT培训资料
选择就业方向:
人工智能物联网
大数据开发/分析
人工智能Python
Java全栈开发
WEB前端+H5

请输入正确的手机号码

请输入正确的验证码

获取验证码

您今天的短信下发次数太多了,明天再试试吧!

提交

我们会在第一时间安排职业规划师联系您!

您也可以联系我们的职业规划师咨询:

小职老师的微信号:z_zhizuobiao
小职老师的微信号:z_zhizuobiao

版权所有 职坐标-一站式IT培训就业服务领导者 沪ICP备13042190号-4
上海海同信息科技有限公司 Copyright ©2015 www.zhizuobiao.com,All Rights Reserved.
 沪公网安备 31011502005948号    

©2015 www.zhizuobiao.com All Rights Reserved

208小时内训课程