.Net配置Swagger包含中文注释与Header参数传递

2023年6月20日发(作者：)

.Net配置Swagger包含中⽂注释与Header参数传递使⽤swagger输出在线api⽂档⾮常⽅便，配置也⾮常的简单，但是有可能会遇到⼀些⼩问题，这⾥我就把⾃⼰遇到的⼀些⼩问题记录⼀下。1、中⽂注释2、如果是分层架构，显⽰实体类的注释3、如果接⼝有token认证，需要在swagger中传递token头部信息分割⾸先在项⽬中使⽤nuget⼯具搜索swagger找到Swashbuckle,选择最新版本安装即可，顺带会⾃动安装⼀个包安装之后打开App_Start⽂件夹中的⽂件直接上最终配置结果 public class SwaggerConfig { public static void Register() { var thisAssembly = typeof(SwaggerConfig).Assembly; uration .EnableSwagger(c => {

ApiVersion("v1", "员⼯信息在线API"); //包含XML⽂件，只要包含了这个⽂件才能正常使⽤swagger在线⽂档 eXmlComments(("{0}/bin/", rectory)); //这个XML是model层输出的XML包含model层的注释 eXmlComments(("{0}/bin/", rectory)); //这个是⾃定义的filter，判断⽅法是否添加头部token使⽤ ionFilter();

//解决同样的接⼝名 传递不同参数 eConflictingActions(apiDescriptions => ()); //⾃定义provider，可以让Controller的注释也显⽰出来

}) .EnableSwaggerUi(c => { //包含⾃定义汉化JS

JavaScript(cutingAssembly(), "");

}); } } Provider((defaultProvider) => new SwaggerCacheProvider(defaultProvider, ("{0}/bin/", 其中的HttpAuthHeaderFilter代码如下public class HttpAuthHeaderFilter : IOperationFilter { ///

/// 是否包含头部 ///

/// /// /// public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription) { if (ters == null) ters = new List(); var filterPipeline = terPipeline(); //判断是否添加权限过滤器 var allowAnonymous = tomAttributes().Any(); var actionFilter = tomAttributes().Any(); var controllerFilter = tomAttributes(true).Any(); //如果包含名字叫TokenAuthorizeAttribute过滤器则给该⽅法的swagger调⽤出添加两个头部信息输⼊框(看个⼈需要) if (actionFilter || controllerFilter) { (new Parameter { name = "Authorization", @in = "header", description = "安全", required = true, type = "string" }); (new Parameter { name = "userid", @in = "header", description = "安全", required = true, type = "string" }); }

} } // var isAuthorized = (filterInfo => ce).Any(filter => filter is IAuthorizationFilSwaggerCacheProvider 代码如下 ///

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

public class SwaggerCacheProvider : ISwaggerProvider { private readonly ISwaggerProvider _swaggerProvider; private static ConcurrentDictionary _cache = new ConcurrentDictionary(); private readonly string _xml; ///

///

///

/// /// xml⽂档路径 public SwaggerCacheProvider(ISwaggerProvider swaggerProvider, string xml) { _swaggerProvider = swaggerProvider; _xml = xml; } public SwaggerDocument GetSwagger(string rootUrl, string apiVersion) { var cacheKey = ("{0}_{1}", rootUrl, apiVersion); SwaggerDocument srcDoc = null; //只读取⼀次 if (!_Value(cacheKey, out srcDoc)) { srcDoc = _gger(rootUrl, apiVersion); Extensions = new Dictionary { { "ControllerDesc", GetControllerDesc() } }; _(cacheKey, srcDoc); } return srcDoc; return srcDoc; } ///

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

/// 所有控制器描述 public ConcurrentDictionary GetControllerDesc() { string xmlpath = _xml; ConcurrentDictionary controllerDescDict = new ConcurrentDictionary(); if ((xmlpath)) { XmlDocument xmldoc = new XmlDocument(); (xmlpath); string type = , path = , controllerName = ; string[] arrPath; int length = -1, cCount = "Controller".Length; XmlNode summaryNode = null; foreach (XmlNode node in Nodes("//member")) { type = utes["name"].Value; if (With("T:")) { //控制器 arrPath = ('.'); length = ; controllerName = arrPath[length - 1]; if (th("Controller")) { //获取控制器注释 summaryNode = SingleNode("summary"); string key = ( - cCount, cCount); if (summaryNode != null && !OrEmpty(ext) && !nsKey(key)) { (key, ()); } } } } } return controllerDescDict; } }直接放到根⽬录即可，否则需要修改配置，⽽且需要右键此JS的属性 ⽣成的操作 设为 嵌⼊的资源，不然的话控制器注释不会⽣效'use strict';rTranslator = { _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 () { try { ($("#input_baseUrl").val()); $.ajax({ type: "get", async: true, url: $("#input_baseUrl").val(), dataType: "json", success: function (data) { var summaryDict = llerDesc; (summaryDict); var id, controllerName, strSummary; $("#resources_container .resource").each(function (i, item) { id = $(item).attr("id"); if (id) { controllerName = ing(9); try { strSummary = summaryDict[controllerName]; if (strSummary) { } } catch (e) { (e); } } }); } }); } catch (e) { (e); } }, _tryTranslate: function (word) { return this._words[$.trim(word)] !== undefined ? this._words[$.trim(word)] : word; }, learn: function (wordsMap) { this._words = wordsMap; }}; $(item).children(".heading").children(".options").first().prepend('

2023年6月20日发(作者：)

.Net配置Swagger包含中⽂注释与Header参数传递使⽤swagger输出在线api⽂档⾮常⽅便，配置也⾮常的简单，但是有可能会遇到⼀些⼩问题，这⾥我就把⾃⼰遇到的⼀些⼩问题记录⼀下。1、中⽂注释2、如果是分层架构，显⽰实体类的注释3、如果接⼝有token认证，需要在swagger中传递token头部信息分割⾸先在项⽬中使⽤nuget⼯具搜索swagger找到Swashbuckle,选择最新版本安装即可，顺带会⾃动安装⼀个包安装之后打开App_Start⽂件夹中的⽂件直接上最终配置结果 public class SwaggerConfig { public static void Register() { var thisAssembly = typeof(SwaggerConfig).Assembly; uration .EnableSwagger(c => {

ApiVersion("v1", "员⼯信息在线API"); //包含XML⽂件，只要包含了这个⽂件才能正常使⽤swagger在线⽂档 eXmlComments(("{0}/bin/", rectory)); //这个XML是model层输出的XML包含model层的注释 eXmlComments(("{0}/bin/", rectory)); //这个是⾃定义的filter，判断⽅法是否添加头部token使⽤ ionFilter();

//解决同样的接⼝名 传递不同参数 eConflictingActions(apiDescriptions => ()); //⾃定义provider，可以让Controller的注释也显⽰出来

}) .EnableSwaggerUi(c => { //包含⾃定义汉化JS

JavaScript(cutingAssembly(), "");

}); } } Provider((defaultProvider) => new SwaggerCacheProvider(defaultProvider, ("{0}/bin/", 其中的HttpAuthHeaderFilter代码如下public class HttpAuthHeaderFilter : IOperationFilter { ///

/// 是否包含头部 ///

/// /// /// public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription) { if (ters == null) ters = new List(); var filterPipeline = terPipeline(); //判断是否添加权限过滤器 var allowAnonymous = tomAttributes().Any(); var actionFilter = tomAttributes().Any(); var controllerFilter = tomAttributes(true).Any(); //如果包含名字叫TokenAuthorizeAttribute过滤器则给该⽅法的swagger调⽤出添加两个头部信息输⼊框(看个⼈需要) if (actionFilter || controllerFilter) { (new Parameter { name = "Authorization", @in = "header", description = "安全", required = true, type = "string" }); (new Parameter { name = "userid", @in = "header", description = "安全", required = true, type = "string" }); }

} } // var isAuthorized = (filterInfo => ce).Any(filter => filter is IAuthorizationFilSwaggerCacheProvider 代码如下 ///

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

public class SwaggerCacheProvider : ISwaggerProvider { private readonly ISwaggerProvider _swaggerProvider; private static ConcurrentDictionary _cache = new ConcurrentDictionary(); private readonly string _xml; ///

///

///

/// /// xml⽂档路径 public SwaggerCacheProvider(ISwaggerProvider swaggerProvider, string xml) { _swaggerProvider = swaggerProvider; _xml = xml; } public SwaggerDocument GetSwagger(string rootUrl, string apiVersion) { var cacheKey = ("{0}_{1}", rootUrl, apiVersion); SwaggerDocument srcDoc = null; //只读取⼀次 if (!_Value(cacheKey, out srcDoc)) { srcDoc = _gger(rootUrl, apiVersion); Extensions = new Dictionary { { "ControllerDesc", GetControllerDesc() } }; _(cacheKey, srcDoc); } return srcDoc; return srcDoc; } ///

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

/// 所有控制器描述 public ConcurrentDictionary GetControllerDesc() { string xmlpath = _xml; ConcurrentDictionary controllerDescDict = new ConcurrentDictionary(); if ((xmlpath)) { XmlDocument xmldoc = new XmlDocument(); (xmlpath); string type = , path = , controllerName = ; string[] arrPath; int length = -1, cCount = "Controller".Length; XmlNode summaryNode = null; foreach (XmlNode node in Nodes("//member")) { type = utes["name"].Value; if (With("T:")) { //控制器 arrPath = ('.'); length = ; controllerName = arrPath[length - 1]; if (th("Controller")) { //获取控制器注释 summaryNode = SingleNode("summary"); string key = ( - cCount, cCount); if (summaryNode != null && !OrEmpty(ext) && !nsKey(key)) { (key, ()); } } } } } return controllerDescDict; } }直接放到根⽬录即可，否则需要修改配置，⽽且需要右键此JS的属性 ⽣成的操作 设为 嵌⼊的资源，不然的话控制器注释不会⽣效'use strict';rTranslator = { _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 () { try { ($("#input_baseUrl").val()); $.ajax({ type: "get", async: true, url: $("#input_baseUrl").val(), dataType: "json", success: function (data) { var summaryDict = llerDesc; (summaryDict); var id, controllerName, strSummary; $("#resources_container .resource").each(function (i, item) { id = $(item).attr("id"); if (id) { controllerName = ing(9); try { strSummary = summaryDict[controllerName]; if (strSummary) { } } catch (e) { (e); } } }); } }); } catch (e) { (e); } }, _tryTranslate: function (word) { return this._words[$.trim(word)] !== undefined ? this._words[$.trim(word)] : word; }, learn: function (wordsMap) { this._words = wordsMap; }}; $(item).children(".heading").children(".options").first().prepend('