.Net Core 3.x Api開發筆記 -- Swagger(七) 在MVC項目中使用 Swagger API文檔

Swagger 可以用來快速生成REST API文檔

其他的不多說，該章節演示如何在 .Net Core Api中使用

在老的項目框架中使用該組件，可以參考另外一篇文章：在MVC項目中使用 Swagger API文檔

1，引用 Swashbuckle.AspNetCore 包

2，在 Startup 中進行註冊 

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "NetCore.Api", Version = "v1" });
});

3，在 Configure(IApplicationBuilder app, IWebHostEnvironment env) 啓用中間件

注意：下邊的 v1 必須和上邊的 v1相同，假如上邊是 v2，下邊相應的也要改成 v2

//啓用中間件服務生成Swagger作爲JSON終結點
app.UseSwagger();
//啓用中間件服務對swagger-ui，指定Swagger JSON終結點
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "NetCore.Swagger v1");
    c.RoutePrefix = string.Empty;   //表示直接 http://localhost:5000 即可顯示 Swagger UI
});

編輯並運行，整體效果如下：

4，Swagger高級用法，使用Swagger爲API文檔增加中文說明信息

 1 //註冊Swagger
 2 services.AddSwaggerGen(c =>
 3 {
 4     c.SwaggerDoc("v1", new OpenApiInfo
 5     {
 6         Title = "NetCore.Swagger",
 7         Version = "v1",
 8         Description = "一個簡單的 ASP.NET Core API",
 9         Contact = new OpenApiContact
10         {
11             Name = "印度阿三",
12             Email = string.Empty,
13             Url = new Uri("https://www.cnblogs.com/peterzhang123/")
14         }
15     });
16 
17     // 爲 Swagger JSON and UI設置xml文檔註釋路徑
18     // 獲取應用程序所在目錄（絕對路徑，不受工作目錄影響，建議採用此方法獲取路徑）
19     // 此方式適用於Windows/Linux 平臺
20     var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
21     var xmlPath = Path.Combine(basePath, "NetCore.Swagger.xml");
22     c.IncludeXmlComments(xmlPath);
23 
24 });

效果如下：

爲接口方法添加文本註釋，

1，勾選XML文檔文件，文件會自動生成

2，添加1591禁用警告顯示

對於 Linux 操作系統，會對xml文件名和路徑區分大小寫，可以在Starup中使用下邊紅框中的代碼解決：

1，給接口添加文本註釋

顯示效果如下：

2，使用 <remarks> </remarks>標籤中可以使用：文本、JSON 或 XML

顯示效果如下：

3，響應狀態碼  文本註釋

[ProducesResponseType(201)]
[ProducesResponseType(400)]

將請求參數全部刪除，然後調用接口，返回結果如下：

 

 

參考文檔：

https://www.cnblogs.com/yilezhu/p/9241261.html