asp.net core使用Swashbuckle.AspNetCore(swagger)生成接口文檔

asp.net core中使用Swashbuckle.AspNetCore生成接口文檔

Swashbuckle.AspNetCore:swagger的asp.net core實現，本文使用版本為v1.1.0
項目地址：https://github.com/domaindrivendev/Swashbuckle.AspNetCore
仔細看了下readme,發現在百度找半天的東西其實readme里面就有...

開局一張圖，然后開始編，一些基本的asp.net core東西就不再贅述，本文只對Swashbuckle.AspNetCore的幾個使用要點進行描述。

如上圖所示，包含功能如下（完整示例見文末）

1. 基礎使用,添加controler的說明(IDocumentFilter)
2. 漢化操作按鈕
3. 添加通用參數(header)-實現IOperationFilter
4. 多版本控制(暫時見demo)
5. 使用JWT的簡單接口驗證(暫時見demo)

構建一個webapi項目並使用swagger

1. 新建asp.net core webapi項目 dotnet new webapi
2. 安裝nuget包：Swashbuckle.AspNetCore,本文使用版本1.1.0,.net core版本2.0+
3. 編輯解決方案添加(或者在vs中項目屬性->生成->勾選生成xml文檔文件)如下配置片段

      <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'"> <DocumentationFile>bin\Debug\netcoreapp2.0\項目名稱.xml</DocumentationFile> </PropertyGroup>

1. 使用Swagger並注入漢化腳本

c.SwaggerDoc配置接口描述信息
c.OperationFilter可通過IOperationFilter接口去添加一些公共的參數
c.DocumentFilter通過IDocumentFilter接口去生成控制器的標簽(描述)
注：ConfigureServices的方法返回值修改了，為了能夠正常的使用ServiceLocator獲取服務

private const string _Project_Name = "AspNetCoreSwaggerDemo";//nameof(AspNetCoreSwaggerDemo); public IServiceProvider ConfigureServices(IServiceCollection services) { services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>(); services.AddSingleton(new ApiTokenConfig("A3FFB16D-D2C0-4F25-BACE-1B9E5AB614A6")); services.AddScoped<IApiTokenService, ApiTokenService>(); services.AddSwaggerGen(c => { typeof(ApiVersions).GetEnumNames().ToList().ForEach(version => { c.SwaggerDoc(version, new Swashbuckle.AspNetCore.Swagger.Info { Version = version, Title = $"{_Project_Name} 接口文檔", Description = $"{_Project_Name} HTTP API " + version, TermsOfService = "None" }); }); var basePath = Microsoft.Extensions.PlatformAbstractions.PlatformServices.Default.Application.ApplicationBasePath; var xmlPath = System.IO.Path.Combine(basePath, $"{_Project_Name}.xml"); c.IncludeXmlComments(xmlPath); //添加自定義參數，可通過一些特性標記去判斷是否添加 c.OperationFilter<AssignOperationVendorExtensions>(); //添加對控制器的標簽(描述) c.DocumentFilter<ApplyTagDescriptions>(); }); services.AddMvc(); return services.BuildServiceProvider(); }

使用InjectOnCompleteJavaScript注入漢化js腳本即可
注：我在這個漢化腳本中添加了保存和讀取賦值token/版本的js代碼
ApiVersions為枚舉，配置api版本，以期通過CustomRoute特性標記解決歷史api問題。

public void Configure(IApplicationBuilder app, IHostingEnvironment env) { app.UseSwagger(); app.UseSwaggerUI(c => { //ApiVersions為自定義的版本枚舉 typeof(ApiVersions) .GetEnumNames() .OrderByDescending(e => e) .ToList() .ForEach(version => { //版本控制 c.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"{_Project_Name} {version}"); }); //注入漢化腳本 c.InjectOnCompleteJavaScript($"/swagger_translator.js"); }); //通過ServiceLocator.Resolve<Service接口>()獲取注入的服務 ServiceLocator.Configure(app.ApplicationServices); app.UseStaticFiles(); app.UseMvc(); }

實現 IDocumentFilter 及 IOperationFilter

通過IOperationFilter接口可以添加一些公共的參數,添加參數到header或者上傳圖片等
通過IDocumentFilter接口可以生成控制器的標簽(描述)
調用方式分別為：
c.OperationFilter<AssignOperationVendorExtensions>();
c.DocumentFilter<ApplyTagDescriptions>();

//添加標簽 public class ApplyTagDescriptions : IDocumentFilter { public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context) { swaggerDoc.Tags = new List<Tag> { //添加對應的控制器描述 這個是好不容易在issues里面翻到的 new Tag { Name = "Account", Description = "登錄相關接口" }, new Tag { Name = "UserCenter", Description = "用戶中心接} }; } }

//添加通用參數，若in='header'則添加到header中,默認query參數 public class AssignOperationVendorExtensions : IOperationFilter { public void Apply(Operation operation, OperationFilterContext context) { operation.Parameters = operation.Parameters ?? new List<IParameter>(); //MemberAuthorizeAttribute 自定義的身份驗證特性標記 var isAuthor = operation != null && context != null && context.ApiDescription.ControllerAttributes().Any(e => e.GetType() == typeof(MemberAuthorizeAttribute)) || context.ApiDescription.ActionAttributes().Any(e => e.GetType() == typeof(MemberAuthorizeAttribute)); if (isAuthor) { //in query header operation.Parameters.Add(new NonBodyParameter() { Name = "x-token", In = "header", //query formData .. Description = "身份驗證票據", Required = false, Type = "string" }); } } }

配置完成后，給Controler，Action添加上注釋和請求類型就可以訪問/swagger查看你的api文檔了~
注：

1. action方法或者控制器(或者繼承的)必須有一個包含[Route]特性標記
2. action方法必須添加請求類型[HttpGet]/[HttpPost]/..

如何自動將token保存並賦值

使用js生成了文本框到.authorize-wrapper,將值保存到了本地存儲中,然后會根據接口版本將版本號參數進行復制

$(function () { //漢化 window.SwaggerTranslator.translate(); /***************下面是添加的token相關代碼*******************/ window.saveToken=function() { var test_token = $("#customtoken").val(); localStorage.setItem("test_x_token", $("#customtoken").val()); $("input[name='X-Token']").val(test_token) } //token保存 var test_token = localStorage.getItem("test_x_token")||""; $(".authorize-wrapper").append("X-Token：<input type='text' id='customtoken' value='" + test_token +"' style='width:50%' /> <button onClick='saveToken()'>保存</button>") $("input[name='X-Token']").val(test_token) $("input[name='X-Version']").val(swaggerUi.api.info.version) });

如何忽略一個接口

為Controller或者Action方法上添加特性標記[ApiExplorerSettings(IgnoreApi =true)]即可

下一篇：Swashbuckle.AspNetCore3.0的二次封裝與使用

文章完整示例

Demo下載
Demo倉庫地址

注：Demo 未修改默認啟動路徑，故應使用 /swagger/ 訪問文檔：，也可自行修改 /Properties/launchSettings.json 配置默認路徑