.Net Core 3.x Api開發筆記 -- Swagger(七)


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


免責聲明!

本站轉載的文章為個人學習借鑒使用,本站對版權不負任何法律責任。如果侵犯了您的隱私權益,請聯系本站郵箱yoyou2525@163.com刪除。



 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM