.net core 3.1 + Swagger 5.0 初步配置-有解無憂

　　附言：賬號創建到現在也6年多了，都沒有寫過任何文章，第一次試水，見諒，這文章是之前.net framework 轉到.net core，搭建swagger的時候，寫在云筆記里面，

　　廢話不說，進入正文，

vs2019創建webapi專案，Nuget引入Swashbuckle.AspNetCore

Startup.cs添加相關配置

ConfigureServices 方法中添加配置，注意大小寫，linux系統區分大小寫

//注冊Swagger生成器，定義一個和多個Swagger 檔案
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
                // 為 Swagger JSON and UI設定xml檔案注釋路徑
                //獲取應用程式所在目錄（絕對，不受作業目錄影響，建議采用此方法獲取路徑）
                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
                var xmlPath = Path.Combine(basePath, "SwaggerCoreTest.xml");
                var xmlPath2 = Path.Combine(basePath, "SwaggerCode.xml");
                c.IncludeXmlComments(xmlPath, true);//true為控制器注釋也讀取出來
                c.IncludeXmlComments(xmlPath2); 
                c.CustomSchemaIds((type) => type.FullName);// 解決相同類名會報錯的問題
            });

Configure方法中添加配置代碼

//啟用中間件服務生成Swagger作為JSON終結點
            app.UseSwagger();
            //啟用中間件服務對swagger-ui，指定Swagger JSON終結點
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
                c.RoutePrefix = string.Empty;//設定首頁為Swagger
                //c.DocExpansion(DocExpansion.None);//設定為none可折疊所有方法
                c.DefaultModelsExpandDepth(-1);//設定為-1 可不顯示models
            });

設定生成XML檔案，專案-屬性-生成，勾選xml檔案檔案

配置Authorization，在AddSwaggerGen中添加

//添加一個必須的全域安全資訊，和AddSecurityDefinition方法指定的方案名稱要一致，這里是Bearer，
                c.AddSecurityRequirement(new OpenApiSecurityRequirement {
                    {
                        new OpenApiSecurityScheme
                        {
                            Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = JwtBearerDefaults.AuthenticationScheme }
                        },
                        new string[] { }
                    }
                });
                c.AddSecurityDefinition(JwtBearerDefaults.AuthenticationScheme, new OpenApiSecurityScheme
                {
                    Description = "JWT授權(資料將在請求頭中進行傳輸) 引數結構: \"Authorization: Bearer {token}\"",
                    Name = "Authorization",//jwt默認的引數名稱
                    In = ParameterLocation.Header,//jwt默認存放Authorization資訊的位置(請求頭中)
                    Type = SecuritySchemeType.ApiKey
                });

配置介面不對外展示，在控制器/行為中添加標簽特性：[ApiExplorerSettings(IgnoreApi = true)]，如

    /// <summary>
    /// 測驗介面
    /// </summary>
    [AllowAnonymous]
    [ApiController]
    public class TestController : ControllerBase
    {
        /// <summary>
        /// Get
        /// </summary>
        /// <returns></returns>
        [HttpGet]
        [Route("api/[controller]")]
        [ApiExplorerSettings(IgnoreApi = true)]
        public string Get()
        {
            return DateTime.Now.ToString();
        }
    }

　　采坑：發布專案后，在服務器專案中未找到對應的xml檔案，處理方式：修改有生成xml檔案的的專案的csproj，添加配置，比如API專案和Model專案都會生成xml檔案，則兩個專案的csproj檔案都加上以下配置，

<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

轉載請註明出處，本文鏈接：https://www.uj5u.com/net/242153.html

標籤：.NET Core

上一篇：【實用小技巧】RSA非對稱加解密及XML&PEM格式互換方案

下一篇：.net core 3.1 + Swagger 5.0 初步配置