1.Swagger UI 是什么？

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

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

2.如何应用？

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

新建一个 API 项目

从 NuGet 下载 Swagger UI 包

配置 Swagger UI

安装好 Swagger 之后，在需要生成 API 文档的项目当中勾选 XML documentation file.



之后我们需要在 StartUp 当中配置 Swagger 相关的设置。

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 过去即可，编写一个编译事件。



编写完成之后我们运行项目，访问 swagger 的页面就会显示成功了：



当然这里的注释是来自于针对 Value 控制器的注释，Swagger 会自动扫描项目所有的控制器类，并且将其展现在 Swagger UI 当中。

DIY Swagger UI

或许到现在 Swagger 已经足够你使用，但是如果你想针对生成的页面进行自定义也是可以的，例如汉化文字？或者在旁边加一个侧边栏？

这些统统都可以实现，细心的同学可能看到了在 StartUp 类的 Configure 方法当中注入了一个 JavaScript 文件，这个文件会在 Swagger UI 加载完成之后调用。那么我们就可以在这个 JS 里面操作 DOM 元素来进行自定义 UI 了。

例如汉化：

'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：

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 即可，这里有个示范：

'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();

});

效果图：