.net5 - 創建Web.Api項目（二）Swagger配置

 Swagger基礎配置

1、非生產環境，不開啟Swagger，根據實際需要決定

2、設置項目屬性

　　xml文件地址：當前地址【Test.WebApi.xml】，其他項目地址【..\Test.WebApi\Test.WebApi.xml】

3、修改服務注冊、注意修改xml文件名稱

        public Startup(IConfiguration configuration, IHostEnvironment env)
        {
            Configuration = configuration;
            Env = env;
        }

        public IHostEnvironment Env { get; }

        private readonly string apiName = "基礎用戶信息服務";

            #region Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Version = "v1",//版本號
                    Title = $"{apiName} 接口文檔——dotnetcore 5.0",//編輯標題
                    Description = $"{apiName} HTTP API V1",//編輯描述
                    //Contact = new OpenApiContact { Name = apiName, Email = "[e-mail]" },//編輯聯系方式
                    License = new OpenApiLicense { Name = apiName }//編輯許可證
                });
                c.OrderActionsBy(o => o.RelativePath);

                var xmlPath = Path.Combine(Env.ContentRootPath, "Test.WebApi.xml");// linux區分大小寫
                c.IncludeXmlComments(xmlPath, true); // 把接口文檔的路徑配置進去。第二個參數表示的是是否開啟包含對Controller的注釋容納【第二個參數可以不加】
            });
            #endregion

 

 Swagger設置參數（折疊、不顯示Models【Schemas】）

                    c.DocExpansion(DocExpansion.None);//DocExpansion設置為none可折疊所有方法
                    c.DefaultModelsExpandDepth(-1);//DefaultModelsExpandDepth設置為-1 可不顯示models【Schemas】

　　

 Swagger控制器的注釋與排序

WebApi項目下新建【Swagger】文件夾，新建【AuthTagDescriptions】並繼承【IDocumentFilter】

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Collections.Generic;

namespace Test.WebApi.Swagger
{
    public class AuthTagDescriptions : IDocumentFilter
    {
        public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
        {
            swaggerDoc.Tags = new List<OpenApiTag>
            {
                new OpenApiTag{ Name = "OrgUnit", Description = "組織單元" },
                new OpenApiTag{ Name = "Employee", Description = "職員維護" },
                new OpenApiTag{ Name = "WeatherForecast", Description = "天氣預報" }
            };
        }
    }
}

 在StartUp類中注入類：

                c.DocumentFilter<AuthTagDescriptions>();// 注入【注釋/排序】文檔

　　

 Swagger版本控制

添加枚舉類（這個不是必須的）：

namespace Test.WebApi.Swagger
{
    /// <summary>
    /// Swagger版本枚舉
    /// </summary>
    public enum ApiVersion
    {
        /// <summary>
        /// v1版本
        /// </summary>
        V1 = 1,
        /// <summary>
        /// v2版本
        /// </summary>
        V2 = 2
    }
}

2、StartUp注冊服務：

                //版本控制
                typeof(ApiVersion).GetEnumNames().ToList().ForEach(version =>
                {
                    c.SwaggerDoc(version, new OpenApiInfo()
                    {
                        Version = version,
                        Title = $"webapi {version}",
                        Description = $"Asp.NetCore Web API {version}"
                    });
                });

 3、啟用Swagger

                    typeof(ApiVersion).GetEnumNames().ToList().ForEach(version =>
                    {
                        c.SwaggerEndpoint($"/swagger/{version}/swagger.json", version);
                    });

  4、在控制器中使用ApiExplorerSettings標記：

    [ApiExplorerSettings(GroupName = "V2")]

 5、注意事項：

(1) 在控制器中使用ApiExplorerSettings標記時，GroupName的值要和ApiVersion中的枚舉名稱一致，否則Swagger列出的API版本列表不會有該控制器的API，導致Swagger網頁中該控制器API文檔不會出現。

(2) 枚舉類型ApiVersion不是必須的，只是用它來獲取版本列表，例如可以使用new List<string>() { "V1", "V2" }.ForEach代替typeof(ApiVersion).GetEnumNames().ToList().ForEach。