傳送門：從0到1手把手教你ASP.NET Core Web API項(xiàng)目配置接口文檔Swagger（一）

一、設(shè)置Swagger頁面為首頁——開發(fā)環(huán)境

我們雖然可以在輸入 /swagger 后順利的訪問 Swagger UI 頁面，但是我們發(fā)現(xiàn)每次運(yùn)行項(xiàng)目都會(huì)默認(rèn)訪問 /weatherforecast 這個(gè)接口，想要將啟動(dòng)頁設(shè)為 /swagger （或者其他頁面）就需要用到配置文件 launchSettings.json。

在如下圖中所示的位置找到并打開 launchSettings.json 文件，在如下圖中所示的地方修改“l(fā)aunchUrl”屬性（有該屬性則修改，無該屬性則手動(dòng)添加）的值由“weatherforecast”為“swagger”并保存，再一次按 F5 鍵運(yùn)行項(xiàng)目就會(huì)發(fā)現(xiàn)直接訪問的地址為“https://localhost:44390/swagger”。

二、設(shè)置Swagger頁面為首頁——生產(chǎn)環(huán)境

上述方法在本地調(diào)試可以直接運(yùn)行，但是如果部署到服務(wù)器，就會(huì)發(fā)現(xiàn)之前的那種默認(rèn)啟動(dòng)首頁無效了，還是需要每次手動(dòng)在域名后邊輸入“/swagger”。

幸運(yùn)的是，Swagger 提供了一個(gè)擴(kuò)展，可以指定一個(gè)空字符作為 Swagger 的地址。在 Startup.cs 文件的 Startup 類的 Configure 方法中配置中間件，如下圖所示，代碼如下所示。

            #region Swagger
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/DocV1/swagger.json", "DocV1");//此為之前配置內(nèi)容
                c.RoutePrefix = "";//此為本次新增配置項(xiàng)
            });
            #endregion

然后把配置文件 launchSettings.json 的 launchUrl 屬性注釋或刪除，如下圖所示，這樣無論是本地開發(fā)環(huán)境還是生產(chǎn)環(huán)境，都可以默認(rèn)加載 Swagger UI 頁面了。

三、添加注釋

1、給接口添加注釋

首先給接口方法加上注釋：打開默認(rèn)生成的 WeatherForecast 控制器，分別給控制器和接口添加注釋，代碼如下所示。

    /// <summary>
    /// 天氣預(yù)報(bào)
    /// </summary>
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        private readonly ILogger<WeatherForecastController> _logger;

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

        /// <summary>
        /// 獲取天氣
        /// </summary>
        /// <returns></returns>
        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            var rng = new Random();
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = rng.Next(-20, 55),
                Summary = Summaries[rng.Next(Summaries.Length)]
            })
            .ToArray();
        }
    }

添加好注釋之后，接下來就需要把注釋信息顯示在 Swagger 中，這時(shí)候需要用到 XML 文檔，因?yàn)樗峭ㄟ^ XML 來維護(hù) Swagger 文檔的一些信息。

鼠標(biāo)右鍵單擊項(xiàng)目名稱，在彈出的菜單中選擇“屬性”選項(xiàng)，在屬性選項(xiàng)卡頁面中的“生成”選項(xiàng)的“輸出”選項(xiàng)的“文檔文件”選項(xiàng)下，勾選“生成包含API文檔的文件”選擇框，“XML 文檔文件路徑”此處使用默認(rèn)位置，故保留為空，如下圖所示。

重新編譯項(xiàng)目后，系統(tǒng)會(huì)在 bin\Debug\net5.0 路徑下默認(rèn)生成一個(gè)與項(xiàng)目名稱相同的 XML 文件，前后對比如下圖所示。

接下來修改 Swagger 服務(wù)注入的代碼。在 Startup.cs 文件的 Startup 類的 ConfigureServices 方法中進(jìn)行修改，代碼如下所示。

            #region Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("DocV1", new OpenApiInfo
                {
                    Version = "v0.1.0",
                    Description = "一個(gè)Swagger教程文檔",
                    Contact = new OpenApiContact
                    {
                        Name = "張歐昊辰",
                        Email = "[email protected]"

                    }
                });


                #region 添加注釋新增內(nèi)容
                var basePath = AppContext.BaseDirectory;
                var projectName = AppDomain.CurrentDomain.FriendlyName;
                var xmlPath = Path.Combine(basePath, projectName + ".xml");
                c.IncludeXmlComments(xmlPath, true);
                #endregion

            });
            #endregion

然后按 F5 啟動(dòng)項(xiàng)目，這樣控制器和接口注釋就都有了，前后對比效果如下圖所示。

2、給Model添加注釋

新建一個(gè)類庫，取名為“AllTestDemo.Model”，步驟如下圖所示，不再做過多文字?jǐn)⑹觥?/p>

當(dāng)類庫創(chuàng)建成功后，我們將“AllTestDemo”下的“WeatherForecast.cs”文件移動(dòng)到新建的類庫“AllTestDemo.Model”下，修改命名空間并添加上注釋，如下圖所示。

我們按照上一小節(jié)中給“AllTestDemo”添加 XML 文檔的方法，同樣給“AllTestDemo.Model”添加 XML 文檔。然后回到 Startup.cs 文件的 Startup 類的 ConfigureServices 方法中進(jìn)行修改，代碼如下所示。

                var xmlModelPath = Path.Combine(basePath, "AllTestDemo.Model.xml");
                c.IncludeXmlComments($"{xmlModelPath}", true);

重新編譯項(xiàng)目后，按 F5 啟動(dòng)項(xiàng)目，這樣 Model 注釋就有了，前后對比效果如下圖所示。

四、去掉 Swagger 警告提示

添加 Swagger 包之后，控制器不填寫相應(yīng)的注釋，項(xiàng)目會(huì)有很多警告，打開錯(cuò)誤列表查看，如下圖所示。

如果我們不想添加注釋，又不想看到這個(gè)警告提示，可以這樣做。

打開“AllTestDemo”的屬性面板，在“生成”選項(xiàng)的“錯(cuò)誤和警告”選項(xiàng)的“取消顯示警告”選項(xiàng)下，添加“;1591”并保存，注意1591前面有分號且是英文輸入法狀態(tài)下輸入的，如下圖所示。

“重新生成解決方案”后，我們看到錯(cuò)誤列表中“AllTestDemo”項(xiàng)目下的警告已經(jīng)沒有了，仍然能看到“AllTestDemo.Model”項(xiàng)目下的警告信息，如下圖所示。

我們可按照上述同樣的方法，對“AllTestDemo.Model”進(jìn)行相同的處理即可。

五、忽略接口信息

如果我們不想展示某個(gè)控制器中全部或部分接口的信息，可以在 Controller? 上或者 Action 上添加 [ApiExplorerSettings(IgnoreApi = true)] 特性來忽略。

1、不添加特性

為了展示效果，在?WeatherForecastController 中添加了一個(gè) POST 訪問類型的方法，代碼如下所示。

        [HttpPost]
        public void Index()
        {
        }

此時(shí) Swagger UI 顯示結(jié)果如下圖所示。

2、在 Action 上添加特性

我們在系統(tǒng)自動(dòng)生成的 Get 方法上添加 [ApiExplorerSettings(IgnoreApi = true)] 特性，如下圖所示。

按 F5 鍵項(xiàng)目啟動(dòng)后 Swagger UI 顯示如下圖所示，對比不添加特性的顯示結(jié)果，我們發(fā)現(xiàn) Get 類型的方法未展示。

3、在 Controller 上添加特性

我們在系統(tǒng)自動(dòng)生成的 WeatherForecastController 上添加 [ApiExplorerSettings(IgnoreApi = true)] 特性，如下圖所示。

按 F5 鍵項(xiàng)目啟動(dòng)后 Swagger UI 顯示如下圖所示，對比不添加特性的顯示結(jié)果，我們發(fā)現(xiàn)沒有接口信息展示。

-------------------------------本篇文章到此結(jié)束-------------------------------------