.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>