swagger的作用和配置使用（多版本操作

在學習net core中接觸到了swagger、學習並記錄

純API項目中 引入swagger可以生成可視化的API接口頁面

   

---

 

引入包

nuget包： Swashbuckle.AspNetCore（最新穩定版）

配置

1.配置Startup類ConfigureServices方法的相關配置

public void ConfigureServices(IServiceCollection services)
        {
            //swagger服務配置
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("V1", new Microsoft.OpenApi.Models.OpenApiInfo
                {
                    Version = "v1",//接口文檔版本
                    Title = "我的接口文檔1.0",//接口文檔標題
                    Description = "我的第一個swagger文檔",//接口文檔描述
                    Contact = new Microsoft.OpenApi.Models.OpenApiContact { Name = "張華", Url = new Uri("http://baidu.com"), Email = "[e-mail]" },
                    License = new Microsoft.OpenApi.Models.OpenApiLicense { Name = "張華", Url = new Uri("http://baidu.com") }
                });
            });
            services.AddControllers();
        }

2.配置Startup類Configure方法的中間件

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });

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

注意：

新建項目第一次配置完成運行的時候可能如下所示。因為 /WeatherForecast 是官方默認的地址

解決方案：Properties文件夾下launchSettings.json文件launchUrl屬性改為null

launchUrl代表瀏覽器里啟動相對的URL

---

4-14更新：

---

 

雖然配置好了swagger，但是眾多接口也不好分辨，因此我們需要給接口添加注釋

 1，右鍵項目屬性-生成-輸出（將文檔文件勾選，路徑可默認可以自己設置）

2，在 Startup.cs文件ConfigureServices方法配置服務（上面配置swagger的地方）

 

 public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            //配置swagger
            services.AddSwaggerGen(a =>
            {
                a.SwaggerDoc("CoreOne_Zhang", new Microsoft.OpenApi.Models.OpenApiInfo
                {
                    Version = "第一版",
                    Title = "CoreOne_Zhang的Swagger第一版",
                    Description = "專有",
                    Contact = new Microsoft.OpenApi.Models.OpenApiContact
                    {
                        Email = "[e-mail]",
                        Url = new Uri("https://jq.qq.com/?_wv=1027&k=GecDlZAd"),
                        Name = "張華"
                    }
                });
              　//xml文檔路徑
                var basePath = AppContext.BaseDirectory;
　　　　　　　　　//將路徑和文件拼接
                var xmlPath = Path.Combine(basePath, "NetCore.OneApi.xml");
　　　　　　　　　//將xml文檔注入。true表示是否顯示控制器注釋，默認false
                a.IncludeXmlComments(xmlPath,true);
            });

 

---

 

2022：4-20更新：Swagger多版本操作

可以將不同的接口分別展示

接上文。設置好swagger后，我們需要設置多個版本（頁面？)

1，可以先創建一個 版本類。（枚舉類型）

 

 

 2，將原本固定寫死的版本號，利用 版本類 循環輸出

typeof循環在SwaggerDoc之外。

 services.AddSwaggerGen(s =>
            {
                typeof(SwaggerType).GetEnumNames().ToList().ForEach(version =>
                {
                    s.SwaggerDoc(version, new OpenApiInfo
                    {
                        Version = version,
                        Title = "歡迎一起學習",
                        Description = "多版本自定義API",
                        Contact = new OpenApiContact { Name = "張華", Url = new Uri("https://jq.qq.com/?_wv=1027&k=mwVO65PG") },
                        License = new OpenApiLicense { Name = "張華", Url = new Uri("https://jq.qq.com/?_wv=1027&k=mwVO65PG") }
                    });
                    var path = System.AppDomain.CurrentDomain.BaseDirectory;
                    var xmlPath = System.IO.Path.Combine(path, "NetNotes.xml");
                    s.IncludeXmlComments(xmlPath, true);
                });
            });

同理，中間件也需要配置循環一下，只要將SwaggerEndpoint，RoutePrefix外面循環  版本輸出即可 

app.UseSwagger();
            app.UseSwaggerUI(a =>
            {
                typeof(SwaggerType).GetEnumNames().ToList().ForEach(V =>
                {
                    a.SwaggerEndpoint($"swagger/{V}/swagger.json", $"版本{V}");
                    a.RoutePrefix = "";
                });
            });

3，將不同的接口展示在不同的版本頁面

只需要加  [ApiExplorerSettings(GroupName ="Zhang")]  Zhang可以替換成你  版本 類里面的任何一個，那么他就只顯示在你規定的版本頁面當中 

運行效果：

 

 

 //效果顯示地址：Swagger UI

//一起學習，Git克隆地址：NetCore學習: NetCore學習 Master：swagger Jwt:Jwt身份驗證登錄 (gitee.com)

 

Ps：個人小小理解，希望有錯誤可以指正