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

港控/mmm° 2023-06-11 11:23 8阅读 0赞

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

使用swagger输出在线api文档非常方便，配置也非常的简单，但是有可能会遇到一些小问题，这里我就把自己遇到的一些小问题记录一下。

1、中文注释

2、如果是分层架构，显示实体类的注释

3、如果接口有token认证，需要在swagger中传递token头部信息

分割

首先在项目中使用nuget工具搜索swagger找到Swashbuckle,选择最新版本安装即可，顺带会自动安装一个Swashbuckle.Core包

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FvMTIzMDU2_size_16_color_FFFFFF_t_70][]

安装之后打开App\_Start文件夹中的SwaggerConfig.cs文件

直接上最终配置结果

1.  `public class SwaggerConfig`
2.  `{`
3.  `public static void Register()`
4.  `{`
5.  `var thisAssembly = typeof(SwaggerConfig).Assembly;`
6.   
7.  `GlobalConfiguration.Configuration`
8.  `.EnableSwagger(c =>`
9.  `{`
10.  
11. `c.SingleApiVersion("v1", "员工信息在线API");`
12. `//包含XML文件，只要包含了这个文件才能正常使用swagger在线文档`
13. `c.IncludeXmlComments(string.Format("{0}/bin/EIP.API.XML", System.AppDomain.CurrentDomain.BaseDirectory));`
14. `//这个XML是model层输出的XML包含model层的注释`
15. `c.IncludeXmlComments(string.Format("{0}/bin/EIP.Model.XML", System.AppDomain.CurrentDomain.BaseDirectory));`
16. `//这个是自定义的filter，判断方法是否添加头部token使用`
17. `c.OperationFilter<HttpAuthHeaderFilter>();`
18.  
19. `//解决同样的接口名 传递不同参数`
20. `c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());`
21. `//自定义provider，可以让Controller的注释也显示出来`
22. `c.CustomProvider((defaultProvider) => new SwaggerCacheProvider(defaultProvider, string.Format("{0}/bin/EIP.API.XML", System.AppDomain.CurrentDomain.BaseDirectory)));`
23.  
24. `})`
25. `.EnableSwaggerUi(c =>`
26. `{`
27. `//包含自定义汉化JS`
28. `c.InjectJavaScript(System.Reflection.Assembly.GetExecutingAssembly(), "EIP.API.swagger.js");`
29.  
30. `});`
31. `}`
32. `}`

其中的HttpAuthHeaderFilter代码如下

1.  `public class HttpAuthHeaderFilter : IOperationFilter`
2.  `{`
3.  `/// <summary>`
4.  `/// 是否包含头部`
5.  `/// </summary>`
6.  `/// <param name="operation"></param>`
7.  `/// <param name="schemaRegistry"></param>`
8.  `/// <param name="apiDescription"></param>`
9.  `public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)`
10.  
11. `{`
12. `if (operation.parameters == null)`
13. `operation.parameters = new List<Parameter>();`
14. `var filterPipeline = apiDescription.ActionDescriptor.GetFilterPipeline(); //判断是否添加权限过滤器`
15. `// var isAuthorized = filterPipeline.Select(filterInfo => filterInfo.Instance).Any(filter => filter is IAuthorizationFilter); //判断是否允许匿名方法`
16. `var allowAnonymous = apiDescription.ActionDescriptor.GetCustomAttributes<AllowAnonymousAttribute>().Any();`
17. `var actionFilter = apiDescription.ActionDescriptor.GetCustomAttributes<TokenAuthorizeAttribute>().Any();`
18. `var controllerFilter = apiDescription.ActionDescriptor.ControllerDescriptor.GetCustomAttributes<TokenAuthorizeAttribute>(true).Any();`
19. `//如果包含名字叫TokenAuthorizeAttribute过滤器则给该方法的swagger调用出添加两个头部信息输入框(看个人需要)`
20. `if (actionFilter || controllerFilter)`
21. `{`
22. `operation.parameters.Add(new Parameter { name = "Authorization", @in = "header", description = "安全", required = true, type = "string" });`
23. `operation.parameters.Add(new Parameter { name = "userid", @in = "header", description = "安全", required = true, type = "string" });`
24. `}`
25.  
26. `}`
27. `}`

SwaggerCacheProvider 代码如下

1.  `/// <summary>`
2.  `/// swagger显示控制器的描述`
3.  `/// </summary>`
4.  `public class SwaggerCacheProvider : ISwaggerProvider`
5.  `{`
6.  `private readonly ISwaggerProvider _swaggerProvider;`
7.  `private static ConcurrentDictionary<string, SwaggerDocument> _cache = new ConcurrentDictionary<string, SwaggerDocument>();`
8.  `private readonly string _xml;`
9.  `/// <summary>`
10. `///`
11. `/// </summary>`
12. `/// <param name="swaggerProvider"></param>`
13. `/// <param name="xml">xml文档路径</param>`
14. `public SwaggerCacheProvider(ISwaggerProvider swaggerProvider, string xml)`
15. `{`
16. `_swaggerProvider = swaggerProvider;`
17. `_xml = xml;`
18. `}`
19.  
20. `public SwaggerDocument GetSwagger(string rootUrl, string apiVersion)`
21. `{`
22.  
23. `var cacheKey = string.Format("{0}_{1}", rootUrl, apiVersion);`
24. `SwaggerDocument srcDoc = null;`
25. `//只读取一次`
26. `if (!_cache.TryGetValue(cacheKey, out srcDoc))`
27. `{`
28. `srcDoc = _swaggerProvider.GetSwagger(rootUrl, apiVersion);`
29.  
30. `srcDoc.vendorExtensions = new Dictionary<string, object> { { "ControllerDesc", GetControllerDesc() } };`
31. `_cache.TryAdd(cacheKey, srcDoc);`
32. `}`
33. `return srcDoc;`
34. `}`
35.  
36. `/// <summary>`
37. `/// 从API文档中读取控制器描述`
38. `/// </summary>`
39. `/// <returns>所有控制器描述</returns>`
40. `public ConcurrentDictionary<string, string> GetControllerDesc()`
41. `{`
42. `string xmlpath = _xml;`
43. `ConcurrentDictionary<string, string> controllerDescDict = new ConcurrentDictionary<string, string>();`
44. `if (File.Exists(xmlpath))`
45. `{`
46. `XmlDocument xmldoc = new XmlDocument();`
47. `xmldoc.Load(xmlpath);`
48. `string type = string.Empty, path = string.Empty, controllerName = string.Empty;`
49.  
50. `string[] arrPath;`
51. `int length = -1, cCount = "Controller".Length;`
52. `XmlNode summaryNode = null;`
53. `foreach (XmlNode node in xmldoc.SelectNodes("//member"))`
54. `{`
55. `type = node.Attributes["name"].Value;`
56. `if (type.StartsWith("T:"))`
57. `{`
58. `//控制器`
59. `arrPath = type.Split('.');`
60. `length = arrPath.Length;`
61. `controllerName = arrPath[length - 1];`
62. `if (controllerName.EndsWith("Controller"))`
63. `{`
64. `//获取控制器注释`
65. `summaryNode = node.SelectSingleNode("summary");`
66. `string key = controllerName.Remove(controllerName.Length - cCount, cCount);`
67. `if (summaryNode != null && !string.IsNullOrEmpty(summaryNode.InnerText) && !controllerDescDict.ContainsKey(key))`
68. `{`
69. `controllerDescDict.TryAdd(key, summaryNode.InnerText.Trim());`
70. `}`
71. `}`
72. `}`
73. `}`
74. `}`
75. `return controllerDescDict;`
76. `}`
77. `}`

swagger.js直接放到根目录即可，否则需要修改配置，而且需要右键此JS的属性 生成的操作 设为 嵌入的资源，不然的话控制器注释不会生效

1.  `'use strict';`
2.  `window.SwaggerTranslator = {`
3.  `_words: [],`
4.   
5.  `translate: function () {`
6.  `var $this = this;`
7.  `$('[data-sw-translate]').each(function () {`
8.  `$(this).html($this._tryTranslate($(this).html()));`
9.  `$(this).val($this._tryTranslate($(this).val()));`
10. `$(this).attr('title', $this._tryTranslate($(this).attr('title')));`
11. `});`
12. `},`
13.  
14. `setControllerSummary: function () {`
15.  
16. `try {`
17. `console.log($("#input_baseUrl").val());`
18. `$.ajax({`
19. `type: "get",`
20. `async: true,`
21. `url: $("#input_baseUrl").val(),`
22. `dataType: "json",`
23. `success: function (data) {`
24.  
25. `var summaryDict = data.ControllerDesc;`
26. `console.log(summaryDict);`
27. `var id, controllerName, strSummary;`
28. `$("#resources_container .resource").each(function (i, item) {`
29. `id = $(item).attr("id");`
30. `if (id) {`
31. `controllerName = id.substring(9);`
32. `try {`
33. `strSummary = summaryDict[controllerName];`
34. `if (strSummary) {`
35. `$(item).children(".heading").children(".options").first().prepend('<li class="controller-summary" style="color:green;" title="' + strSummary + '">' + strSummary + '</li>');`
36. `}`
37. `} catch (e) {`
38. `console.log(e);`
39. `}`
40. `}`
41. `});`
42. `}`
43. `});`
44. `} catch (e) {`
45. `console.log(e);`
46. `}`
47. `},`
48. `_tryTranslate: function (word) {`
49. `return this._words[$.trim(word)] !== undefined ? this._words[$.trim(word)] : word;`
50. `},`
51.  
52. `learn: function (wordsMap) {`
53. `this._words = wordsMap;`
54. `}`
55. `};`
56.  
57.  
58. `/* jshint quotmark: double */`
59. `window.SwaggerTranslator.learn({`
60. `"Warning: Deprecated": "警告：已过时",`
61. `"Implementation Notes": "实现备注",`
62. `"Response Class": "响应类",`
63. `"Status": "状态",`
64. `"Parameters": "参数",`
65. `"Parameter": "参数",`
66. `"Value": "值",`
67. `"Description": "描述",`
68. `"Parameter Type": "参数类型",`
69. `"Data Type": "数据类型",`
70. `"Response Messages": "响应消息",`
71. `"HTTP Status Code": "HTTP状态码",`
72. `"Reason": "原因",`
73. `"Response Model": "响应模型",`
74. `"Request URL": "请求URL",`
75. `"Response Body": "响应体",`
76. `"Response Code": "响应码",`
77. `"Response Headers": "响应头",`
78. `"Hide Response": "隐藏响应",`
79. `"Headers": "头",`
80. `"Try it out!": "试一下！",`
81. `"Show/Hide": "显示/隐藏",`
82. `"List Operations": "显示操作",`
83. `"Expand Operations": "展开操作",`
84. `"Raw": "原始",`
85. `"can't parse JSON. Raw result": "无法解析JSON. 原始结果",`
86. `"Model Schema": "模型架构",`
87. `"Model": "模型",`
88. `"apply": "应用",`
89. `"Username": "用户名",`
90. `"Password": "密码",`
91. `"Terms of service": "服务条款",`
92. `"Created by": "创建者",`
93. `"See more at": "查看更多：",`
94. `"Contact the developer": "联系开发者",`
95. `"api version": "api版本",`
96. `"Response Content Type": "响应Content Type",`
97. `"fetching resource": "正在获取资源",`
98. `"fetching resource list": "正在获取资源列表",`
99. `"Explore": "浏览",`
100. `"Show Swagger Petstore Example Apis": "显示 Swagger Petstore 示例 Apis",`
101. `"Can't read from server. It may not have the appropriate access-control-origin settings.": "无法从服务器读取。可能没有正确设置access-control-origin。",`
102. `"Please specify the protocol for": "请指定协议：",`
103. `"Can't read swagger JSON from": "无法读取swagger JSON于",`
104. `"Finished Loading Resource Information. Rendering Swagger UI": "已加载资源信息。正在渲染Swagger UI",`
105. `"Unable to read api": "无法读取api",`
106. `"from path": "从路径",`
107. `"server returned": "服务器返回"`
108. `});`
109. `$(function () {`
110. `window.SwaggerTranslator.translate();`
111. `window.SwaggerTranslator.setControllerSummary();`
112. `});`

其他的一些必要操作：项目右键属性-生成- xml文档生成

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FvMTIzMDU2_size_16_color_FFFFFF_t_70 1][]

如果model层也需要注释的话，那么也需要将model层设置输出XML文档，注意此处设置的是DEBUG模式，如果release版本也需要的话，则也要选择release版本然后勾选输出。

不过我这边有点小问题就是model层的XML在realease版本下即使勾选了也没有输出到bin目录。

最终效果如下

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FvMTIzMDU2_size_16_color_FFFFFF_t_70 2][]

完成

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FvMTIzMDU2_size_16_color_FFFFFF_t_70]: /images/20230531/ed0f69e935304999b3942fd09d9a8f00.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FvMTIzMDU2_size_16_color_FFFFFF_t_70 1]: /images/20230531/8b2f7ab75a3d4c5f9b08c5b71913ae69.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FvMTIzMDU2_size_16_color_FFFFFF_t_70 2]: /images/20230531/5a9dd29a7cd9417e9c29e77890592135.png