ASP.NET Core Web API中使用Swagger
本節導航
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的服務代碼。
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動詞使用不同的顏色代碼。當我們單擊任何操作方法時，它將詢問參數詳細信息，當我們單擊“非?！卑粹o時，它將向Web API發送請求。
??在測試我們的WebAPI時，Swagger只需要最少的配置即可。
??那么，如果我們想要在UI上顯示代碼注釋應該怎么辦呢？
??在.NET Core中，我們可以通過在項目屬性窗口的“構建”選項卡下設置“XML文檔文件”屬性來獲取XML注釋。
??默認情況下，Swagger UI不顯示此文檔。我們需要傳遞包含exmlcomments的路徑。
參考
https://www.c-sharpcorner.com/article/test-your-asp-net-core-web-api-with-swagger/
http://www.zhikestreet.com/Home/Detail/6/
原文地址：https://www.cnblogs.com/lucky_hu/p/11130209.html
.NET社區新聞，深度好文，歡迎訪問公眾號文章匯總?http://www.csharpkit.com?
總結
以上是生活随笔為你收集整理的ASP.NET Core Web API中使用Swagger的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： ASP.NET Core on K8S学
- 下一篇： C# 8.x 先睹为快