5.4 ABP分布式服务 - 集成SwaggerUI

5.4.1 简介

从官网得知，开启Swagger，你可以获得一个交互式的文档，生成和发现客户端SDK。

5.4.2 ASP.NET Core

1. 安装

你可以很容易的集成Swagger到基于ASP.NET Core的 ABP项目。

2. 安装Nuget包

安装 Swashbuckle nuget包到你的Web项目。

3. 配置

在 Startup.cs 文件中找到 ConfigureServices 方法，并在该方法中为Swagger添加配置代码。

  1. public IServiceProvider ConfigureServices(IServiceCollection services)
  2. {
  3.     //其它代码...
  5.     services.AddSwaggerGen();
  7.     //其它代码...
  8. }

然后在 Startup.cs 的 Configure 方法中添加如下配置：

  1. public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
  2. {
  3.     //其它代码...
  5.     app.UseSwagger();
  6.     app.UseSwaggerUi(); //URL: /swagger/ui
  7. }

在你使用 swgger ui 测试动态 Web Api 的时候，为了同时能够发送 CSRF token，你需要添加 swgger ui的 index.html 文件到你的web项目。该文件应该精确的放在 wwwroot\swagger\ui 文件夹下。然后你需要更改swagger ui的index.html中已定义的 onComplete 方法，如下所示：

  1. onComplete: function(swaggerApi, swaggerUi){
  2.   if(typeof initOAuth == "function") {
  3.     initOAuth({
  4.       clientId: "your-client-id",
  5.       clientSecret: "your-client-secret-if-required",
  6.       realm: "your-realms",
  7.       appName: "your-app-name",
  8.       scopeSeparator: " ",
  9.       additionalQueryStringParams: {}
  10.     });
  11.   }
  13.   if(window.SwaggerTranslator) {
  14.     window.SwaggerTranslator.translate();
  15.   }
  17.   var csrfToken = abp.security.antiForgery.getToken();
  18.   var csrfCookieAuth = new SwaggerClient.ApiKeyAuthorization(abp.security.antiForgery.tokenHeaderName, csrfToken, "header");
  19.   swaggerUi.api.clientAuthorizations.add(abp.security.antiForgery.tokenHeaderName, csrfCookieAuth);
  21. }

了解更多的配置选项请参考Swashbuckle的文档。

5.4.3 ASP.NET 5.x

1. 安装

你可以很容易的集成Swagger到基于ABP创建的项目中。

2. Nuget安装

安装 Swashbuckle.Core到你的WebApi项目或者Web项目

2. 配置

在你的模块的 Initialize 方法中添加配置Swagger的代码，如下所示：

  1. public class SwaggerIntegrationDemoWebApiModule : AbpModule
  2. {
  3.     public override void Initialize()
  4.     {
  5.         //其它代码...
  7.         ConfigureSwaggerUi();
  8.     }
  10.     private void ConfigureSwaggerUi()
  11.     {
  12.         Configuration.Modules.AbpWebApi().HttpConfiguration
  13.             .EnableSwagger(c =>
  14.             {
  15.                 c.SingleApiVersion("v1", "SwaggerIntegrationDemo.WebApi");
  16.                 c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
  17.             })
  18.             .EnableSwaggerUi(c =>
  19.             {
  20.                 c.InjectJavaScript(Assembly.GetAssembly(typeof(AbpProjectNameWebApiModule)), "AbpCompanyName.AbpProjectName.Api.Scripts.Swagger-Custom.js");
  21.             });
  22.     }
  23. }

注意：在配置swagger ui的时候，我们注入的脚本文件名称是 Swagger-Custom.js。当你使用swagger ui来测试动态web api的时候，这个脚本文件被用来添加 CSRF token 到你的请求头中。你需要添加这个文件到你的WebApi项目中，并使用它的逻辑名(例如：你的项目名称.文件夹名称.脚本文件名称)在InjectJavaScript方法中注入它，该脚本文件一定要设置为 Embedded Resource。

该文件中的脚本内容如下：

  1. var getCookieValue = function(key) {
  2.     var equalities = document.cookie.split('; ');
  3.     for (var i = 0; i < equalities.length; i++) {
  4.         if (!equalities[i]) {
  5.             continue;
  6.         }
  8.         var splitted = equalities[i].split('=');
  9.         if (splitted.length !== 2) {
  10.             continue;
  11.         }
  13.         if (decodeURIComponent(splitted[0]) === key) {
  14.             return decodeURIComponent(splitted[1] || '');
  15.         }
  16.     }
  18.     return null;
  19. };
  21. var csrfCookie = getCookieValue("XSRF-TOKEN");
  22. var csrfCookieAuth = new SwaggerClient.ApiKeyAuthorization("X-XSRF-TOKEN", csrfCookie, "header");
  23. swaggerUi.api.clientAuthorizations.add("X-XSRF-TOKEN", csrfCookieAuth);

更多配置请参考Swashbuckle文档

5.4.4. 测试

按照如上配置后，让我们来浏览下文档 /swagger/ui/index：

集成Swagger UI - 图1

你能看到所有的 Web Api Controllers 包括动态 Web Api Controllers，并且现在你可以测试它们。