以目前流行的前后端分离模式来看，ABP框架更适用于后端开发，而对API接口的管理就成了一项必不可少的功能。
1.安装Swashbuckle.AspNetCore
使用Nuget管理器在分布式服务层和展现层AbpDemo.Web安装Swashbuckle.AspNetCore程序包，包含Swashbuckle.AspNetCore.Swagger、Swashbuckle.AspNetCore.SwaggerGen、Swashbuckle.AspNetCore.SwaggerUI三项。
2.配置Swagger选项
对于Swagger的配置主要是在AbpDemo.Web项目中的Startup启动类。
在ConfigureServices方法中添加配置：
services.AddSwaggerGen(options =>{options.SwaggerDoc("v1", new OpenApiInfo {Title = "AbpDemo", Version = "v1.0",Description="",TermsOfService=new Uri("/ludewig"),Contact = new OpenApiContact {Name="ludewig",Email="panshuairg@",Url=new Uri("/ludewig") }});options.DocInclusionPredicate((docName, description) => true);});
在Configure方法中添加配置：
app.UseSwagger();app.UseSwaggerUI(options =>{options.SwaggerEndpoint("/swagger/v1/swagger.json", "Demo API v1");});
此时启动项目，输入默认地址http://xxx:xx/swagger/index.html就可以访问swagger的API接口管理界面。
3.添加注释信息
但是现在界面包含的信息还比较少，在代码中的注释还没加进来。
打开应用层AbpDemo.Application的属性界面，选择“生成”选项，勾选“XML文档文件”，这样再次编译项目时，代码注释会以XML文件形式生成到AbpDemo.Web项目中。
同时还要在AbpDemo.Web项目中修改Startup启动类以便于Swagger能够读取到生成的XML文件。
services.AddSwaggerGen(options =>{options.SwaggerDoc("v1", new OpenApiInfo {Title = "AbpDemo", Version = "v1.0",Description="",TermsOfService=new Uri("/ludewig"),Contact = new OpenApiContact {Name="ludewig",Email="panshuairg@",Url=new Uri("/ludewig") }});options.DocInclusionPredicate((docName, description) => true);var filePath = bine(AppContext.BaseDirectory, "AbpDemo.Application.xml");options.IncludeXmlComments(filePath);});
4.使用API接口管理界面
经过上面的配置步骤后再次启动项目，可以查看到swagger的界面了。
通过swagger的API管理界面，可以对API接口的输入输出数据结构进行查看和测试。
5.ABP框架中Swagger的其他配置
5.1关于CSRF
按照前面的步骤完成对Swagger的配置后，启动项目，测试接口却发现报错了。这其实是ABP框架本身的机制导致的。ABP框架默认是开启CSRF保护的，也就是启动了对Cross-Site Request Forgery (CSRF) 跨站请求伪造的防护机制，客户端必须携带可信的token令牌才能访问API接口。解决这个问题有两种方式：
关闭CSRF保护
在Startup启动类的ConfigureServices方法中注释如下代码
services.AddControllersWithViews(options =>{//注释下列代码关闭CSRF保护options.Filters.Add(new AutoValidateAntiforgeryTokenAttribute());})
添加CSRF token
添加用于写入token信息的脚本文件，设置文件属性为“嵌入的资源”并注入到项目中。在Startup启动类中注入脚本文件。
app.UseSwaggerUI(options =>{//...options.InjectJavascript("ui/abp.js");//注入脚本文件});
脚本文件内容如下：
var getCookieValue = function(key) {var equalities = document.cookie.split('; ');for (var i = 0; i < equalities.length; i++) {if (!equalities[i]) {continue;}var splitted = equalities[i].split('=');if (splitted.length !== 2) {continue;}if (decodeURIComponent(splitted[0]) === key) {return decodeURIComponent(splitted[1] || '');}}return null;};var csrfCookie = getCookieValue("XSRF-TOKEN");var csrfCookieAuth = new SwaggerClient.ApiKeyAuthorization("X-XSRF-TOKEN", csrfCookie, "header");swaggerUi.api.clientAuthorizations.add("X-XSRF-TOKEN", csrfCookieAuth);
5.2添加自定义首页
路径http://xxxx:xx/swagger/index.html对应的首页是系统默认的API管理界面，内嵌在Swashbuckle.AspNetCore程序包中，页面包含内容如下：
<!-- HTML for static distribution bundle build --><!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>%(DocumentTitle)</title><link rel="stylesheet" type="text/css" href="./swagger-ui.css" ><link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" /><link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" /><style>html{box-sizing: border-box;overflow: -moz-scrollbars-vertical;overflow-y: scroll;}*,*:before,*:after{box-sizing: inherit;}body{margin:0;background: #fafafa;}</style>%(HeadContent)</head><body><div id="swagger-ui"></div><!-- Workaround for /swagger-api/swagger-editor/issues/1371 --><script>if (window.navigator.userAgent.indexOf("Edge") > -1) {console.log("Removing native Edge fetch in favor of swagger-ui's polyfill")window.fetch = undefined;}</script><script src="./swagger-ui-bundle.js"> </script><script src="./swagger-ui-standalone-preset.js"> </script><script>window.onload = function() {var configObject = JSON.parse('%(ConfigObject)');var oauthConfigObject = JSON.parse('%(OAuthConfigObject)');// If validatorUrl is not explicitly provided, disable the feature by setting to nullif (!configObject.hasOwnProperty("validatorUrl"))configObject.validatorUrl = null// If oauth2RedirectUrl isn't specified, use the built-in defaultif (!configObject.hasOwnProperty("oauth2RedirectUrl"))configObject.oauth2RedirectUrl = window.location.href.replace("index.html", "oauth2-redirect.html").split('#')[0];// Apply mandatory parametersconfigObject.dom_id = "#swagger-ui";configObject.presets = [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset];configObject.layout = "StandaloneLayout";// Begin Swagger UI call regionconst ui = SwaggerUIBundle(configObject);ui.initOAuth(oauthConfigObject);// End Swagger UI call regionwindow.ui = ui}</script></body></html>
可以看到默认的首页已经提供了配置对象ConfigObject、验证授权配置对象OAuthConfigObject、验证地址ValidatorUrl、验证授权重定向地址OAuth2RedirectUrl。
如果觉得官方提供的首页在样式或功能上不满足要求，可以创建自定义的首页添加到wwwroot目录下，并设置文件属性为“嵌入的资源”。然后在Startup启动类的Configure方法中设置自定义的首页。
app.UseSwaggerUI(options =>{//...options.IndexStream = () => Assembly.GetExecutingAssembly().GetManifestResourceStream("AbpDemo.Web.wwwroot.swagger.ui.index.html");//...});
更多详细功能可以参考swagger官方文档
源代码示例-Github
如果觉得《ABP学习实践(五)--引入Swagger对API接口进行管理》对你有帮助，请点赞、收藏，并留下你的观点哦！
