本篇同步發文在個人Blog: 一袋.NET要扛幾樓？打造容器化的ASP.NET Core網站！系列文章 - (6) 建立商品服務的Api - 4

 1. 安裝Swagger

　在CatalogApi專案右鍵[管理NuGet套件]，安裝Swagger相關的套件：：

　　Swashbuckle.AspNetCore.SwaggerGen , 版本 5.6.1

　　Swashbuckle.AspNetCore.SwaggerUI , 版本 5.6.1

 2. 在Startup.cs註冊與使用Swagger

2.1 ConfigureServices的服務註冊

　　需使用SwaggerGen註冊Swagger的功能，並加上對此Api專案的描述。

    public void ConfigureServices(IServiceCollection services)
    {
    	// other code...
    	
    	services.AddSwaggerGen(options =>
    	{
    		options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
    		{
    			Version = "v1",
    			Title = "Catalog API",
    			Description = "Catalog apis"
    		});
    	});
    }

2.2 Configure加上Swagger的Middleware

　　在Pipeline加上Swagger的Middleware，放在app.UseRouting之前，指定它的json endpoint與名稱。

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
	// other code...

	app.UseSwagger()
	   .UseSwaggerUI(c =>
	   {
		   c.SwaggerEndpoint(
			   $"/swagger/v1/swagger.json",
			   "CatalogAPI V1");
	   });

	app.UseRouting();

	// other code...
}

 3. 修改launchSettings.json

　　從VS執行程式的參數會依照launchSettings.json，包含URL與其他環境變數。而原先預設在IIS Express的launchUrl是weatherforecast，將它改成swagger，這樣VS啟用IIS的設定會用swagger：

　　而它主要是讀取商品的照片，並回傳File Result：

    {
      "$schema": "http://json.schemastore.org/launchsettings.json",
      "iisSettings": {
        "windowsAuthentication": false,
        "anonymousAuthentication": true,
        "iisExpress": {
          "applicationUrl": "http://localhost:13914",
          "sslPort": 0
        }
      },
      "profiles": {
        "IIS Express": {
          "commandName": "IISExpress",
          "launchBrowser": true,
          "launchUrl": "swagger",
          "environmentVariables": {
            "ASPNETCORE_ENVIRONMENT": "Development"
          }
        },
        "CatalogApi": {
          "commandName": "Project",
          "launchBrowser": true,
          "environmentVariables": {
            "ASPNETCORE_ENVIRONMENT": "Development"
          }
        }
      }
    }

 4. 移除預設專案的範例

　　原先建立Web API專案時，會有WeatherForecast的Controller與Model，將這些都移除。

 5. 新增商品的圖片

　　本系列使用的商品圖片來自於 opengameart.org的Game Icons Knight Armor ，裡面有10種裝備的圖片，在專案根目錄新增wwwroot資料夾和下一層的Pictures資料夾，將這10張圖片都放進此Pictures，如圖1

圖1

 6. VS執行

　　開啟Debug，看到畫面是Swagger的介面，包含我們所寫的Controller的Action，如圖2。每個API都能點籍，並按下Try it out的按鈕，輸入參數做實際的API運作。

圖2

　　比如點Http Get的/api/Catalog/Items，輸入查詢的catalog type id、pagesize與pageIndex，將回傳一組Json物件，如圖3。

圖3

    點Http Post的/api/Catalog/Items，輸入要新增CatalogItem的Json，送出後將回傳Statuc code 201的結果，也確認資料庫有新增這一筆資料，如圖4、圖5與圖6。

圖4

圖5

圖6

　　其他的API都可以運作，這就不再舉例。

　　下一篇將把Catalog Api上到Docker，整合為容器化的服務。