在 DotNetCore 下的 Swagger UI 自定义操作

1.Swagger UI 是什么？

Swagger UI 是一个在线的 API 文档生成与测试工具，你可以将其集成在你的 API 项目当中。

  • 支持 API 自动同步生成文档
  • 高度自定义，可以自己扩展功能
  • 前后端分离时方便前端进行 API 接口测试

2.如何应用？

这里仅介绍在 DotNetCore 下如何集成 Swagger UI。

新建一个 API 项目

Image1

从 NuGet 下载 Swagger UI 包

Image2

配置 Swagger UI

安装好 Swagger 之后，在需要生成 API 文档的项目当中勾选 XML documentation file. Image3 之后我们需要在 StartUp 当中配置 Swagger 相关的设置。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

public class Startup
{
	public Startup(IConfiguration configuration)
	{
		Configuration = configuration;
	}

	public IConfiguration Configuration { get; }

	public void ConfigureServices(IServiceCollection services)
	{
		services.AddMvc();

		services.AddSwaggerGen(options =>
		{
			options.SwaggerDoc("v1", new Info() { Title = "Swagger Test UI", Version = "v1" });
			options.CustomSchemaIds(type => type.FullName); // 解决相同类名会报错的问题
			options.IncludeXmlComments(Path.Combine(Directory.GetCurrentDirectory(), "SwaggerUIDemo.xml")); // 标注要使用的 XML 文档
		});
	}

	public void Configure(IApplicationBuilder app, IHostingEnvironment env)
	{
		if (env.IsDevelopment())
		{
			app.UseDeveloperExceptionPage();
		}

                app.UseStaticFiles();
		app.UseSwagger();
		// 在这里面可以注入
		app.UseSwaggerUI(options => 
		{
			options.InjectOnCompleteJavaScript("/swagger/ui/zh_CN.js"); // 加载中文包
			options.SwaggerEndpoint("/swagger/v1/swagger.json", "HKERP API V1");
		});
                app.UseMvc();
	}
}

当然我们直接运行的时候会提示找不到 XML 文件，因为我们使用的是 Path.Combine(Directory.GetCurrentDirectory(), "SwaggerUIDemo.xml")，SO，我们在项目变异的时候手动 COPY 过去即可，编写一个编译事件。 Image4 编写完成之后我们运行项目，访问 swagger 的页面就会显示成功了： Image5 当然这里的注释是来自于针对 Value 控制器的注释，Swagger 会自动扫描项目所有的控制器类，并且将其展现在 Swagger UI 当中。

DIY Swagger UI

或许到现在 Swagger 已经足够你使用，但是如果你想针对生成的页面进行自定义也是可以的，例如汉化文字？或者在旁边加一个侧边栏？ 这些统统都可以实现，细心的同学可能看到了在 StartUp 类的 Configure 方法当中注入了一个 JavaScript 文件，这个文件会在 Swagger UI 加载完成之后调用。那么我们就可以在这个 JS 里面操作 DOM 元素来进行自定义 UI 了。

例如汉化：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

'use strict';

/**
 * Translator for documentation pages.
 *
 * To enable translation you should include one of language-files in your index.html
 * after <script src='lang/translator.js' type='text/javascript'></script>.
 * For example - <script src='lang/ru.js' type='text/javascript'></script>
 *
 * If you wish to translate some new texsts you should do two things:
 * 1. Add a new phrase pair ("New Phrase": "New Translation") into your language file (for example lang/ru.js). It will be great if you add it in other language files too.
 * 2. Mark that text it templates this way <anyHtmlTag data-sw-translate>New Phrase</anyHtmlTag> or <anyHtmlTag data-sw-translate value='New Phrase'/>.
 * The main thing here is attribute data-sw-translate. Only inner html, title-attribute and value-attribute are going to translate.
 *
 */
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')));
        });
    },

    _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();
});

这里我们如果想要在 Swagger UI 上针对控制器来应用注释的话，就需要自己实现一个 DocumentFiliter，这里我们直接继承自 IDocumentFiliter，来实现一个自定义的 Filiter：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

public class CustomDocumentFiliter : IDocumentFilter
{
	public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
	{
		SetContorllerDescription(swaggerDoc.Extensions);
	}

	private void SetContorllerDescription(Dictionary<string, object> extensionsDict)
	{
		string _xmlPath = Path.Combine(Directory.GetCurrentDirectory(), "HKERP.Application.xml");
		ConcurrentDictionary<string, string> _controllerDescDict = new ConcurrentDictionary<string, string>();

		if (File.Exists(_xmlPath))
		{
			XmlDocument _xmlDoc = new XmlDocument();
			_xmlDoc.Load(_xmlPath);

			string _type = string.Empty, _path = string.Empty, _controllerName = string.Empty;
			XmlNode _summaryNode = null;

			foreach (XmlNode _node in _xmlDoc.SelectNodes("//member"))
			{
				_type = _node.Attributes["name"].Value;

				if (_type.StartsWith("T:") && !_type.Contains("T:HKERP.HKERPAppServiceBase") && !_type.Contains("T:HKERP.Net.MimeTypes.MimeTypeNames"))
				{
					_summaryNode = _node.SelectSingleNode("summary");
					string[] _names = _type.Split('.');
					string _key = _names[_names.Length - 1];
					if (_key.IndexOf("AppService", _key.Length - "AppService".Length, StringComparison.Ordinal) > -1)
					{
						_key = _key.Substring(0, _key.Length - "AppService".Length);
					}

					if (_summaryNode != null && !string.IsNullOrEmpty(_summaryNode.InnerText) && !_controllerDescDict.ContainsKey(_key))
					{
						_controllerDescDict.TryAdd(_key, _summaryNode.InnerText.Trim());
					}
				}
			}

			extensionsDict.TryAdd("ControllerDescription", _controllerDescDict);
		}
	}
}

这里我们直接读取生成的 XML 文档，并且生成一个字典添加到 SwaggerDocument 的 Extensions 属性当中，这样的话，在 Swagger UI 加载的时候，调用的 JSON 接口就回附带上我们添加的内容，这个时候只需要在 JS 文件当中获取并且填充 UI 即可，这里有个示范：

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

'use strict';

/**
 * Translator for documentation pages.
 *
 * To enable translation you should include one of language-files in your index.html
 * after <script src='lang/translator.js' type='text/javascript'></script>.
 * For example - <script src='lang/ru.js' type='text/javascript'></script>
 *
 * If you wish to translate some new texsts you should do two things:
 * 1. Add a new phrase pair ("New Phrase": "New Translation") into your language file (for example lang/ru.js). It will be great if you add it in other language files too.
 * 2. Mark that text it templates this way <anyHtmlTag data-sw-translate>New Phrase</anyHtmlTag> or <anyHtmlTag data-sw-translate value='New Phrase'/>.
 * The main thing here is attribute data-sw-translate. Only inner html, title-attribute and value-attribute are going to translate.
 *
 */
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')));
        });
    },

    _tryTranslate: function (word) {
        return this._words[$.trim(word)] !== undefined ? this._words[$.trim(word)] : word;
    },

    learn: function (wordsMap) {
        this._words = wordsMap;
    },

    setControllerSummary: function () {
        var _str = $("#input_baseUrl").val();
        $.ajax({
            type: "get",
            async: true,
            url: $("#input_baseUrl").val(),
            dataType: "json",
            success: function (data) {
                //console.log(data)
                var toggleEndpointList = [];
                var summaryDict = data.ControllerDescription;
                var id, controllerName, strSummary;
                $('body').append('<ul class="leftMenu"></ul>');
                $("#resources .resource").each(function (i, item) {
                    id = $(item).attr("id");
                    if (id) {
                        controllerName = id.substring(9);
                        strSummary = summaryDict[controllerName];
                        if (strSummary) {
                            console.log($(item))
                            $(item).children(".heading").children("h2").children('a').text(strSummary);
                            $(item).children(".heading").children(".options").prepend('<li class="controller-summary" title="' + strSummary + '">' + strSummary + '</li>');
                            $('.leftMenu').append('<li class="menuLi" title="' + strSummary + '"><a href=""  class="menuLiA">' + strSummary + '</a></li>');
                            toggleEndpointList.push($(item).attr('id'))
                        }
                    }
                });
                for (var i = 0; i < document.getElementsByClassName('menuLiA').length;i++){
                    var menuLiA = document.getElementsByClassName('menuLiA');                   
                    menuLiA[i].setAttribute('href', '#'+toggleEndpointList[i])
                }
                
            }
        });
    },
};


/* 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 () {
    debugger;
    window.SwaggerTranslator.translate();
    window.SwaggerTranslator.setControllerSummary();
});

效果图： Image6

© 2020 - 2024 Zony 的博客
Built with Hugo
主题 Stack 由 Jimmy 设计