.NetCore使用Swagger+API多版本控制的流程是什么

這篇文章主要講解了“.NetCore使用Swagger+API多版本控制的流程是什么”，文中的講解內容簡單清晰，易于學習與理解，下面請大家跟著小編的思路慢慢深入，一起來研究和學習“.NetCore使用Swagger+API多版本控制的流程是什么”吧！

本文實例環境及版本.NetCore3.1、Swagger6.1

現在的開發大部分都是前后端分離的模式了，后端提供接口，前端調用接口。后端提供了接口，需要對接口進行測試，之前都是使用瀏覽器開發者工具，或者寫單元測試，再或者直接使用Postman，但是現在這些都已經out了。后端提供了接口，如何跟前端配合說明接口的性質，參數等這也是一個問題。有沒有一種工具可以根據后端的接口自動生成接口文檔，說明接口的性質，參數等信息，又能提供接口調用等相關功能呢？答案是有的。Swagger 是一個規范和完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。而作為.net core開發，Swashbuckle是swagger應用的首選！

總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法、參數和模型緊密集成到服務器端的代碼，允許 API 來始終保持同步。Swagger 讓部署管理和使用功能強大的 API 從未如此簡單。

整個swagger頁面訪問流程如下：

　　1、瀏覽器輸入swaggerUI頁面地址，比如：http://localhost:5000/swagger/index.html，這個地址是可配置的

　　2、請求被SwaggerUI中間件攔截，然后返回頁面，這個頁面是嵌入的資源文件，也可以設置成外部自己的頁面文件（使用外部靜態文件攔截）

　　3、頁面接收到Swagger的Index頁面后，會根據SwaggerUI中間件中使用SwaggerEndpoint方法設置的文檔列表，加載第一個文檔，也就是獲取文檔架構信息swagger.json

　　4、瀏覽器請求的swagger.json被Swagger中間件攔截，然后解析屬于請求文檔的所有接口，并最終返回一串json格式的數據

　　5、瀏覽器根據接收到的swagger,json數據呈現UI界面

一、Swagger基本使用

1、新建NetCore項目，添加相關Controller并添加引用Swashbuckle.AspNetCore.Swagger

2、在Startup中添加配置

在ConfigureServices中注入Swashbuckle服務

services.AddSwaggerGen(c =>
{
     c.SwaggerDoc("V1", new OpenApiInfo
     {
           //版本 
           Version = "V1",
           //標題
           Title = $"接口文檔-NetCore3.1",
           //描述
           Description = $"NetCore Http API v1",
           //聯系方式
           Contact = new OpenApiContact { Name = "測試", Email = "", Url = new Uri("https://www.cnblogs.com/mzflog/") },
           License = new OpenApiLicense { Name = "測試2", Url = new Uri("https://www.cnblogs.com/mzflog/") }
      });
      // 加載XML注釋
      c.IncludeXmlComments(XmlCommentsFilePath);
 });

新增XmlCommentsFilePath 屬性，此時需要引用Microsoft.Extensions.PlatformAbstractions

/// <summary>
 /// 獲取當前項目名的XML文件
 /// </summary>
 static string XmlCommentsFilePath
 {
     get
     {
         var basePath = PlatformServices.Default.Application.ApplicationBasePath;
         var fileName = typeof(Startup).GetTypeInfo().Assembly.GetName().Name + ".xml";
         return Path.Combine(basePath, fileName);
     }
  }

在Configure中添加Swagger中間件UseSwagger，UseSwaggerUI

UseSwagger：添加Swagger中間件，主要用于攔截swagger.json請求，從而可以獲取返回所需的接口架構信息

UseSwaggerUI：添加SwaggerUI中間件，主要用于攔截swagger/index.html頁面請求，返回頁面給前端

app.UseSwagger();
 app.UseSwaggerUI(c =>
 {
     c.SwaggerEndpoint($"/swagger/V1/swagger.json", $"NetCore V1");
     //c.RoutePrefix = string.Empty;     //如果是為空 訪問路徑就為 根域名/index.html,注意localhost:8001/swagger是訪問不到的
     //路徑配置，設置為空，表示直接在根域名（localhost:8001）訪問該文件
     c.RoutePrefix = "swagger"; // 如果你想換一個路徑，直接寫名字即可，比如直接寫c.RoutePrefix = "swagger"; 則訪問路徑為 根域名/swagger/index.html
 });

右鍵項目屬性在生成中添加XML

此時通過http://localhost:端口號/swagger即可訪問

二、Swagger結合版本控制

版本控制的好處：

　　1、有助于及時推出功能, 而不會破壞現有系統。

2、它還可以幫助為選定的客戶提供額外的功能。

1、添加對Microsoft.AspNetCore.Mvc.Versioning和Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer的引用，本文使用版本4.1.0

2、在ConfigureServices中

services.AddApiVersioning(option =>
{
      // 可選，為true時API返回支持的版本信息
      option.ReportApiVersions = true;
      // 請求中未指定版本時默認為1.0
      option.DefaultApiVersion = new ApiVersion(1, 0);
      //版本號以什么形式，什么字段傳遞
      option.ApiVersionReader = ApiVersionReader.Combine(new HeaderApiVersionReader("api-version"));

      // 在不提供版本號時，默認為1.0  如果不添加此配置，不提供版本號時會報錯"message": "An API version is required, but was not specified."
      //option.AssumeDefaultVersionWhenUnspecified = true;
      //默認以當前最高版本進行訪問
      //option.ApiVersionSelector = new CurrentImplementationApiVersionSelector(option);
 }).AddVersionedApiExplorer(opt =>
 {
      //以通知swagger替換控制器路由中的版本并配置api版本
      opt.SubstituteApiVersionInUrl = true;
      // 版本名的格式：v+版本號
      opt.GroupNameFormat = "'v'VVV";
      //是否提供API版本服務
      opt.AssumeDefaultVersionWhenUnspecified = true;
 });

//方式一 （不建議使用）   此種方式報警告：ASP0000 從應用程序代碼調用“BuildServiceProvider”會導致創建單例服務的附加副本。考慮替代方案，例如將依賴注入服務作為“配置”的參數
 services.AddSwaggerGen(options =>
 {
       // 解析IApiVersionDescriptionProvider服務
       var provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();

       //為每個發現的API版本添加一個swagger文檔 可跳過不需要記錄的
       foreach (var description in provider.ApiVersionDescriptions)
       {
            options.SwaggerDoc(description.GroupName, CreateInfoForApiVersion(description));
       }
　　　　 //加載XML注釋  并啟用控制器的注釋信息默認為false不啟用
       options.IncludeXmlComments(XmlCommentsFilePath,true);
  });


//方式二 （建議使用）
services.AddSwaggerGen();
//解決上面報ASP0000警告的方案
services.AddOptions<SwaggerGenOptions>()
        .Configure<IApiVersionDescriptionProvider>((options, service) =>
        {
             options.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
             // 添加文檔信息
             foreach (var item in service.ApiVersionDescriptions)
             {
                 options.SwaggerDoc(item.GroupName, CreateInfoForApiVersion(item));
             }
             //給swagger添加過濾器
             //options.OperationFilter<SwaggerParameterFilter>();
             // 加載XML注釋
             options.IncludeXmlComments(XmlCommentsFilePath, true);
        });

添加CreateInfoForApiVersion方法

static OpenApiInfo CreateInfoForApiVersion(ApiVersionDescription description)
 {
       var info = new OpenApiInfo()
       {
             //標題
             Title = $".NET Core API for 測試項目 {description.ApiVersion}",
             //當前版本
             Version = description.ApiVersion.ToString(),
             //文檔說明
             Description = "api項目 當前環境-" + EnvironmentName,
             //聯系方式
             Contact = new OpenApiContact() { Name = "標題", Email = "", Url = null },
             TermsOfService = new Uri(""),
             //許可證
             License = new OpenApiLicense() { Name = "文檔", Url = new Uri("") }
         };　　　　　 //當有棄用標記時的提示信息
         if (description.IsDeprecated)
         {
             info.Description += " - 此版本已放棄兼容";
         }
         return info;
   }

3、在Configure中添加

IApiVersionDescriptionProvider：用于枚舉定義的API版本的API版本描述符提供程序

public void Configure(IApplicationBuilder app, IWebHostEnvironment env, IApiVersionDescriptionProvider provider)

//添加Swagger中間件，主要用于攔截swagger.json請求，從而可以獲取返回所需的接口架構信息
app.UseSwagger(opt =>
{
      //路由模板，默認值是/swagger/{documentName}/swagger.json，這個屬性很重要！而且這個屬性中必須包含{documentName}參數。
      //opt.RouteTemplate= "/swagger/{documentName}/swagger.json";
      // 表示按Swagger2.0格式序列化生成swagger.json，這個不推薦使用，盡可能的使用新版本的就可以了
      //opt.SerializeAsV2
 });
 //添加SwaggerUI中間件，主要用于攔截swagger / index.html頁面請求，返回頁面給前端
 app.UseSwaggerUI(options =>
 {
       // 為每個版本創建一個JSON
       foreach (var description in provider.ApiVersionDescriptions)
       {
             //這個屬性是往SwaggerUI頁面head標簽中添加我們自己的代碼，比如引入一些樣式文件，或者執行自己的一些腳本代碼
             //options.HeadContent += $"<script type='text/javascript'>alert('歡迎來到SwaggerUI頁面')</script>";

             //展示默認頭部顯示的下拉版本信息
             //options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
             //自由指定頭部顯示的下拉版本內容
             options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", "coreApi" + description.ApiVersion);

              //如果是為空 訪問路徑就為 根域名/index.html,注意localhost:8001/swagger是訪問不到的
              //options.RoutePrefix = string.Empty;
              // 如果你想換一個路徑，直接寫名字即可，比如直接寫c.RoutePrefix = "swagger"; 則訪問路徑為 根域名/swagger/index.html
              options.RoutePrefix = "swagger";
        }
  });

4、在api的Controller中添加版本

[ApiVersion("1.0", Deprecated = false)] //Deprecated是否棄用該版本 默認為false不棄用。即使標記了棄用此接口還是會顯示，只是做個提示此版本將會被棄用了。
 [Route("api/[controller]")]
 [ApiController]
 //[ApiExplorerSettings(IgnoreApi = true)] 隱藏該接口Controller
 public class ValuesController : Controller [Obsolete] //棄用該Action方法 [ApiExplorerSettings(IgnoreApi = true)] //隱藏該Action方法 public IEnumerable<string> Get()

為體驗版本控制在新建一個控制器并添加 [ApiVersion("2.0")]

此時訪問頁面，在右側的下拉框中可選擇不同的版本，會展示不同版本下的控制器。

感謝各位的閱讀，以上就是“.NetCore使用Swagger+API多版本控制的流程是什么”的內容了，經過本文的學習后，相信大家對.NetCore使用Swagger+API多版本控制的流程是什么這一問題有了更深刻的體會，具體使用情況還需要大家實踐驗證。這里是億速云，小編將為大家推送更多相關知識點的文章，歡迎關注！