日期：2023年 08月 05日

標籤： C# Asp.net Core Web MVC Web Swagger Html

摘要：C# 學習筆記

第一部分：範例專案說明

Step 1：範例專案架構

第二部分：如何啟用Swagger

Step 1：Nuget安裝

安裝以下2個Swagger相依性套件

Swashbukle.AspNetCore
Swashbukle.AspNetCore.Swagger

Step 2：Program.cs設定

安裝完成Nuget後，再添加Service與Build相關Swagger相關代碼
對應專案架構的：1. 初始化

using Microsoft.OpenApi.Models;
using System.Reflection;

var builder = WebApplication.CreateBuilder(args);

\\配置其他Service...

//1. Nuget安裝Swagger
//2-1. 增加以下代碼，啟用Swagger
builder.Services.AddSwaggerGen(o =>
{
    o.SwaggerDoc("v1", new OpenApiInfo { Title = "產生Swagger文件", Version = "v1" });
    // 2-2. 加入xml檔案到Swagger
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    o.IncludeXmlComments(xmlPath, includeControllerXmlComments: true);
});

var app = builder.Build();

\\配置其他app configure...

if (app.Environment.IsDevelopment())
{
    //3. 只有Dev(Debug Mode)時才會啟用
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });
}

\\配置其他app configure...

app.Run();

Step 3：控制器代碼-1

以下使用HomeController.cs中，當檢視器(View)與Action(API)共存的情況下，如何出現在Swagger

using Microsoft.AspNetCore.Mvc;

namespace NetCoreSwaggerWebSiteAdditionExample.Controllers
{
    public class HomeController : Controller
    {
        private readonly ILogger<HomeController> _logger;

        public HomeController(ILogger<HomeController> logger)
        {
            _logger = logger;
        }

        public IActionResult Index()
        {
            return View();
        }

        public IActionResult Privacy()
        {
            return View();
        }

        //1. 標記出Swagger辨識的Attributer
        [HttpGet]
        [Route("api/Home/GetPersonalInfo")]
        public IActionResult GetPersonalInfo(int userId)
        {            
            return Ok();
        }

        //2. 標記出Swagger辨識的Attributer
        [HttpPost]
        [Route("api/Home/GetDeposit")]        
        public IActionResult GetDeposit(int userId, string password)
        {
            return Ok();
        }
    }
}

Step 4：控制器代碼-2

標註Attribute，必須有Http的Action與指定Route，那麼Swagger才會辨識出

[HttpGet]
[Route("api/Home/GetPersonalInfo")]

Step 5：Demo成果

執行網站，並且在根目錄下追加路徑： /Swagger/index.html
就會跳轉到Swagger文件資訊頁面，可以看到Api資訊已出現

http://localhost:7206/swagger/index.html

第三部分：如何配置API的顯示

Step 1：配置區域

在實際開發時，專案可能會多種控制器共存
此時功能相同但對象不同的控制器，會有命名相同的問題
以Areas資料夾區分功能是其中一種解決方案，以此專案為例：
External：第三方用API
Mobile：行動裝置用API

Step 2：基底控制器-1

對應專案架構 3. 基礎配置
建立一個BaseController
掛上Attribute => [ApiExplorerSettings(IgnoreApi = true)]
表示不顯示在Swagger上

using Microsoft.AspNetCore.Mvc;

namespace NetCoreSwaggerWebSiteAdditionExample.Base
{    
    [ApiExplorerSettings(IgnoreApi = true)]
    public class BaseController : Controller
    {
    }
}

Step 3：基底控制器-2

對應專案架構 3. 基礎配置
再建立一個OpenController，繼承於BaseController
任何繼承此OpenController的控制器都會開放顯示
Attribute說明如下：

using Microsoft.AspNetCore.Mvc;

namespace NetCoreSwaggerWebSiteAdditionExample.Base
{
    [Route($@"Open/[controller]/[action]")]
    [Area("Open")]
    [ApiExplorerSettings(IgnoreApi = false)]
    public class OpenBaseController: BaseController
    {
    }
}

Step 4：Areas控制器配置-1

為了展式效果，假設外部第三方API會開放在Swagger顯示
在Areas/External/MemberController.cs 配置Http Action
其中繼承了 OpenBaseController 表示會在Swagger中顯示

using Microsoft.AspNetCore.Mvc;
using NetCoreSwaggerWebSiteAdditionExample.Base;

namespace NetCoreSwaggerWebSiteAdditionExample.Areas.External
{
    //繼承OpenBaseController 將會開放
    public class MemberController : OpenBaseController
    {
        /// <summary>
        /// 第三方API
        /// </summary>
        /// <param name="userId">測試</param>
        /// <returns></returns>
        [HttpGet]        
        public IActionResult GetPersonalInfo(int userId)
        {
            return Ok("GetPersonalInfo Successful");
        }

        //也可以強制不開放
        [ApiExplorerSettings(IgnoreApi = true)]
        public IActionResult GetPersonalInfoNoShow(int userId)
        {
            return Ok("GetPersonalInfo Successful");
        }
    }
}

Step 5：Areas控制器配置-2

為了展式效果，假設外部Mobile API會開放在Swagger顯示
在Areas/Mobile/MemberController.cs 配置Http Action
其中繼承了 BaseController 表示在Swagger中不顯示

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using NetCoreSwaggerWebSiteAdditionExample.Base;

namespace NetCoreSwaggerWebSiteAdditionExample.Areas.Mobile
{
    //繼承BaseController 將不會開放
    public class MemberController : BaseController
    {
        [AllowAnonymous]
        [HttpGet]
        public IActionResult GetPersonalInfo(int userId)
        {
            return Ok("Mobile GetPersonalInfo Successful");
        }
    }
}

Step 6：Demo成果

執行網站，並且在根目錄下追加路徑： /Swagger/index.html
就會跳轉到Swagger文件資訊頁面，可以看到External Api資訊已出現
並且Mobile的API因為繼承BaseController.cs所以不會顯示
未來開發時可以以此做區隔是否開放

http://localhost:7206/swagger/index.html