附言:賬号建立到現在也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>