asp.net core系列 37 WebAPI 使用OpenAPI (swagger)中間件
一.概述
在使用Web API時,對于開發人員來說,了解其各種方法可能是一項挑戰。在ASP.NET Core上,Web api 輔助工具介紹二個中間件,包括:Swashbuckle和NSwag .NET。本篇先講Swashbuckle。二者都使用Swagger規範,Swagger也稱為OpenAPI,解決了為Web API生成有用文檔和幫助頁面的問題。它提供了諸如互動式文檔,用戶端SDK生成和API可發現性等好處。
(1) Swashbuckle.AspNetCore是一個開源項目,用于為ASP.NET Core Web API生成Swagger文檔。
(2) NSwag是另一個開源項目,該項目将Swashbuckle和AutoRest(用戶端生成)的功能內建在一個工具鍊中。用于生成Swagger文檔并将Swagger UI或ReDoc內建到ASP.NET Core Web API中。此外,NSwag還提供了為API生成C#和TypeScript用戶端代碼的方法。
1.1 什麼是Swagger / OpenAPI
Swagger是一種與開發語言無關的規範,用于描述REST API。Swagger項目被捐贈給OpenAPI計劃,現在稱為OpenAPI。兩個名稱可互換使用; 但是,OpenAPI是首選。它允許計算機和IT人了解服務的功能,而無需直接通路實作(源代碼,網絡通路,文檔)。一個目标是最小化連接配接不相關服務所需的工作量。另一個目标是減少準确記錄服務所需的時間。
1.2 Swagger規範(swagger.json)
Swagger流程的核心是Swagger規範,預設情況下是一個名為swagger.json的文檔。它由Swagger工具鍊(或其第三方實作)根據你的服務生成。它描述了 API 的功能以及使用 HTTP 對其進行通路的方式。 它驅動 Swagger UI,并由工具鍊用來啟用發現和用戶端代碼生成。
1.3 Swagger UI
Swagger UI 提供了基于 Web 的 UI,它使用生成的 Swagger 規範提供有關服務的資訊。 Swashbuckle 和 NSwag 均包含 Swagger UI 的嵌入式版本,是以可使用中間件注冊調用将該嵌入式版本托管在 ASP.NET Core 應用中。
二. 添加 Swashbuckle中間件
關于Swashbuckle有三個主要組成部分:
(1) Swashbuckle.AspNetCore.Swagger: 一個Swagger對象模型和中間件,用于将
SwaggerDocument
對象公開為JSON端點。
(2) Swashbuckle.AspNetCore.SwaggerGen:一個Swagger生成器,可
SwaggerDocument
直接從路由,控制器和模型建構對象。它通常與Swagger端點中間件結合使用,以自動顯示Swagger JSON。
(3) Swashbuckle.AspNetCore.SwaggerUI: Swagger UI工具的嵌入式版本。它解釋 Swagger JSON 以建構描述 Web API 功能的可自定義的豐富體驗。它包括用于公共方法的内置測試工具。
2.1 包安裝
通過vs 2017的程式包管理器控制台,運作安裝Install-Package Swashbuckle.AspNetCore -Version 5.0.0-beta。 安裝資訊如下所示:
![](https://img.laitimes.com/img/9ZDMuAjOiMmIsIjOiQnIsISM9AnYldnJwAzN9c3Pn5GcuQ0MlMWbidXNT5EMjR0T31EVOhXUU1EdVRlT5lFRNlXUU90dVRUT6FEVPhXQq1EdBpmTxUEVOhHO510drRVT3lkeMdXWU5EeVRVT2NmMiNnSywEd5ITW110MaZHetlVdO1GT0UERNl3YXJGc5kHT20ESjBjUIF2Lc12bj5SYphXa5VWen5WY35iclN3Ztl2Lc9CX6MHc0RHaiojIsJye.png)
2.2 配置Swagger中間件
将 Swagger 生成器添加到
Startup.ConfigureServices
方法中的服務集合中
//将SwaggerGen服務添加到服務集合中, OpenApiInfo是它的自帶類。
services.AddSwaggerGen(c =>
{
//注意不能用大寫V1,不然老報錯,Not Found /swagger/v1/swagger.json
c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});
Startup.Configure
方法中,啟用中間件為生成的 JSON 文檔和 Swagger UI 提供服務
public void Configure(IApplicationBuilder app)
{
//...
// Enable middleware to serve generated Swagger as a JSON endpoint.
app.UseSwagger();
// Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
// specifying the Swagger JSON endpoint.
// UseSwaggerUI方法調用啟用靜态檔案中間件。
app.UseSwaggerUI(c=> {
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
app.UseMvc();
}
啟動應用,并導航到
http://localhost:<port>/swagger/index.html
下,檢視
Web API生成Swagger文檔
如下所示(一個網頁,二處截圖拼在一起):
三.自定義和擴充
Swagger 提供了為對象模型進行歸檔和自定義 UI 以比對你的主題的選項。
3.1 API 資訊和說明的配置
可以在
AddSwaggerGen
方法中配置,添加諸如作者,許可證和描述之類的資訊,通過OpenApiInfo類來添加。
services.AddSwaggerGen(c =>
{
//注意不能用大寫V1,不然老報錯,Not Found /swagger/v1/swagger.json
c.SwaggerDoc("v1", new OpenApiInfo{
Version = "v1",
Title = "ToDo API",
//服務描述
Description = "A simple example ASP.NET Core Web API",
//API服務條款的URL
TermsOfService = new Uri("http://tempuri.org/terms"),
Contact = new OpenApiContact
{
Name = "Joe Developer",
Email = "[email protected]"
},
License = new OpenApiLicense
{
Name = "Apache 2.0",
Url = new Uri("http://www.apache.org/licenses/LICENSE-2.0.html")
}
});
});
Swagger UI 顯示版本的資訊:
3.2 XML注釋api
在“解決方案資料總管”中右鍵單擊該項目,然後選擇“編輯 <project_name>.csproj”。 手動添加以下代碼到 .csproj 檔案中。
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
接下來配置 Swagger 以使用生成的 XML 檔案。對于 Linux 作業系統,檔案名和路徑區分大小寫。例如,“TodoApi.XML”檔案在 Windows 上有效,但在 CentOS 上無效。配置和解決如下所示:
services.AddSwaggerGen(c =>
{
//...配置SwaggerDoc 省略
// Set the comments path for the Swagger JSON and UI.
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
});
接着對每個api方法添加操作說明注釋,以删除api來描述如下所示:
/// <summary>
/// 删除一個TodoItem
/// </summary>
/// <remarks>
/// Sample request:
/// DELETE: api/Todo/2
/// </remarks>
/// <param name="id"></param>
/// <returns>不傳回内容</returns>
/// <response code="204">删除成功,不傳回内容</response>
/// <response code="404">删除失敗,未找到該記錄</response>
[HttpDelete("{id}", Name = "DeleteTodoItem")]
[ProducesResponseType(204)]
[ProducesResponseType(404)]
public async Task<IActionResult> DeleteTodoItem(long id)
{
var todoitem = await _context.TodoItems.FindAsync(id);
if (todoitem == null)
{
return NotFound();
}
_context.TodoItems.Remove(todoitem);
await _context.SaveChangesAsync();
return NoContent();
}
啟動程式後,Swagger UI 顯示的Delete删除api的描述如下圖。還可以點選try it out按鈕進行測試删除,圖中顯示server response 傳回204删除成功。
3.2 資料注釋
使用 System.ComponentModel.DataAnnotations 命名空間中的屬性來修飾模型,以幫助驅動 Swagger UI 元件。下面将
[Required]
屬性添加到
TodoItem
類的
Name
屬性:
[Required]
public string Name { get; set; }
此屬性的狀态更改 UI 行為并更改基礎 JSON 架構:
将
[Produces("application/json")]
屬性添加到 API 控制器。 這樣做的目的是聲明控制器的操作支援 application/json 的響應内容類型:
[Produces("application/json")]
[Route("api/[controller]")]
[ApiController]
public class TodoController : ControllerBase
{
//..
}
最後還可以自定義Swagger UI,這裡不在示範,可以檢視官網。更多功能介紹上github。
參考文獻:
Swashbuckle 和 ASP.NET Core 入門
github
posted on 2019-03-05 11:24 花陰偷移 閱讀(...) 評論(...) 編輯 收藏