本節導航
- Swagger介紹
- 在ASP.NET CORE 中的使用swagger
在軟件開發中,管理和測試API是一件重要而富有挑戰性的工作。在我之前的文章《研發團隊,請管好你的API文檔》 也專門闡述了通過文檔管理工具,來保證API文檔和代碼的一致性,這樣更加有助於團隊的協作。
以往我們總是通過第三方平台工具來管理我們的API文檔,如eolinker。在測試方面,我們也會依賴fiddler,PostMan這樣的工具。
Swagger兼具了API文檔管理和測試的功能,而且保證了代碼和文檔的一致性。它提供了無需任何實現邏輯的RESTfulAPI的UI表示。它允許用戶在沒有任何代碼訪問的情況下了解服務的功能，並減少創建服務文檔的時間。
1 Swagger介紹
Swagger兼具了API文檔管理和測試的功能,而且保證了代碼和文檔的一致性。它提供了無需任何實現邏輯的RESTfulAPI的UI表示。它允許用戶在沒有任何代碼訪問的情況下了解服務的功能，並減少創建服務文檔的時間。
swagger使用swagger工具基於我們編寫的服務代碼生成的swagger.json文件來生成文檔管理界面。此文件描述服務的功能，即服務支持多少方法，並提供有關方法參數的信息。使用這個文件，SwaggerUI生成客戶機代碼。下面是swagger.json文件的一個示例。
{
"swagger": "2.0",
"info": {
"version": "1.0",
"title": "My Demo API"
},
"paths": {
"/api/Values": {
"get": {
"tags": ["Values"],
"summary": "Get values",
"operationId": "Get",
"consumes": [],
"produces": ["text/plain", "application/json", "text/json"],
"parameters": [],
"responses": {
"200": {
"description": "Success",
"schema": {
"uniqueItems": false,
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"post": {
"tags": ["Values"],
"operationId": "Post",
"consumes": ["application/json-patch+json", "application/json", "text/json", "application/*+json"],
"produces": [],
"parameters": [{
"name": "value",
"in": "body",
"required": false,
"schema": {
"type": "string"
}
}],
"responses": {
"200": {
"description": "Success"
}
}
}
}
},
"definitions": {}
}
在APS.NET Core Web API 中，我們可以用Swashbuckle.AspNetCore 和 NSwag這兩個包來實現Swagger,而且二者都是github上開源的。此外，nswag還提供了生成typescript客戶端代碼的方法以及用於API的服務代碼。
1.2 TPL
任務並行庫（TPL）是System.Threading和System.Threading.Tasks命名空間中的一組公共類型和API。
TPL動態地擴展並發度，以最有效地使用所有可用的處理器。通過使用TPL，您可以最大限度地提高代碼的性能，同時專注於您的代碼的業務實現。
從.NET Framework 4開始，TPL是編寫多線程和並行代碼的首選方式。
2 在ASP.NET CORE 中的使用swagger
這里以Swashbuckle.AspNetCore來實現。
以下是在ASP.net Core Web API中配置Swagger的步驟:
1. 安裝Swashbuckle.AspNetCore
PM> Install-Package Swashbuckle.AspNetCore
2. 配置swagger中間件
要將swagger middle添加到請求管道，需要在startup類的configureService方法中添加swaggergen方法。在這里，我們可以定義一個或多個swagger XML文檔。
Startup.cs
// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1.0", new Info { Title = "My Demo API", Version = "1.0" });
c.IncludeXmlComments(System.IO.Path.Combine(System.AppContext.BaseDirectory, "ZhiKeCore.API.xml"));
});
}
如果要啟用這個中間件，我們還需要在startup類的configure方法中調用useswagger方法。在這里，我們還需要配置swagerendpoint來生成UI。useswagegrui將添加一個靜態文件中間件來加載swager.json文件。
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseMvc();
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1.0/swagger.json", "My Demo API (V 1.0)");
});
}
以上是配置swagger的基本步驟,如果我們想使用Visual Studio在開發環境中啟動Swagger，還需要做一點設置。選擇項目-屬性-Debug,修改啟動瀏覽器(Launch Browser)的值為swagger。
當我們啟動程序以后,可以看到如下界面:
正如我們在這里看到的，它對每個HTTP動詞使用不同的顏色代碼。當我們單擊任何操作方法時，它將詢問參數詳細信息，當我們單擊“非常”按鈕時，它將向Web API發送請求。
在測試我們的WebAPI時，Swagger只需要最少的配置即可。
那么，如果我們想要在UI上顯示代碼注釋應該怎么辦呢？
在.NET Core中，我們可以通過在項目屬性窗口的“構建”選項卡下設置“XML文檔文件”屬性來獲取XML注釋。
默認情況下，Swagger UI不顯示此文檔。我們需要傳遞包含exmlcomments的路徑。
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1.0", new Info { Title = "My Demo API", Version = "1.0" });
c.IncludeXmlComments(System.IO.Path.Combine(System.AppContext.BaseDirectory, "ZhiKeCore.API.xml"));
});
}
參考
- https://www.c-sharpcorner.com/article/test-your-asp-net-core-web-api-with-swagger/
- http://www.zhikestreet.com/Home/Detail/6/
關注
請關注微信公眾號智客坊。
