ASP.NET Core Web API中使用Swagger

戎"碼"一生發表於2019-07-04
ASP.NETWebAPISwagger

本節導航

  • 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"));
            });
        }

使用場景

參考

關注
  請關注微信公眾號智客坊。

使用場景

相關文章