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的服務代碼。

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/

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