更新

如果想直接在域名的根目錄直接載入 swagger 比如訪問：localhost:8001 就能訪問，可以這樣設定：

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");
    c.RoutePrefix = "";//路徑配置，設定為空，表示直接訪問該檔案
});

WHY

BEFORE

為何直接 F5 執行，首頁還是無法載入？

介面雖有，但是卻沒有相應的文字說明？

專案開發中的實體類是如何在Swagger中展示的？

對於介面是如何加許可權驗證的？

HOW

1、設定swagger ui頁面為首頁

在上一回中我們提到，我們直接F5執行專案，出現了系統預設頁，

雖然可以在輸入/swagger後，順利的訪問swagger ui頁，但是我們發現每次執行專案，都會預設訪問api/values這個介面，我想要將啟動頁設為swagger（或者是任意一個頁面），你就需要用到了

**設定檔案launchSettings.json **了：

然後你再一次F5 執行，就會發現不一樣了，其他的配置，以及以後部署中的設定，我們會在以後的文章中都有提到。

2、接下來，我們就需要解決第二個問題，如何增加文字說明，就是傳說中的註釋

右鍵專案名稱=>屬性=>生成，勾選“輸出”下面的“xml文件檔案”，系統會預設生成一個，當然老規矩，你也可以自己起一個名字

• .net core 2.1 新不同
• 生成的預設路徑不一樣了，沒有了netcoreapp2.0資料夾

這個時候，先別忙著執行專案，作為老司機的我，只要是改程式碼或者配置檔案，儲存後，第一件事就是看看有沒有錯誤，一看，咦~~~果然，雖然是警告，可以強迫症呀，一看還挺多

別慌！一看，哦！原來是swagger把一些介面方法都通過xml檔案配置了，就是剛剛上文提到的，所以我們只需要加上方法註釋就可以辣，可以左斜槓/，連續三下即可

現在呢，配置好了xml檔案，接下來需要讓系統啟動的時候，去讀取這個檔案了，重新編輯Startup.cs，修改ConfigureServices函式：

 public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc();

            #region Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v0.1.0",
                    Title = "Blog.Core API",
                    Description = "框架說明文件",
                    TermsOfService = "None",
                    Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "Blog.Core", Email = "[email protected]", Url = "https://www.jianshu.com/u/94102b59cc2a" }
                });

                //就是這裡

                var basePath = PlatformServices.Default.Application.ApplicationBasePath;
                var xmlPath = Path.Combine(basePath, "Blog.Core.xml");//這個就是剛剛配置的xml檔名
                c.IncludeXmlComments(xmlPath,true);//預設的第二個引數是false，這個是controller的註釋，記得修改
            });
            #endregion
        }

View Code

• .Net Core 2.1 新不同 感謝網友反饋@，@
• 獲取專案路徑的方式和2.0版本不一樣

     var basePath = Microsoft.DotNet.PlatformAbstractions.ApplicationEnvironment.ApplicationBasePath;
     var xmlPath = Path.Combine(basePath, "Blog.Core.xml");//這個就是剛剛配置的xml檔名
     c.IncludeXmlComments(xmlPath, true);//預設的第二個引數是false，這個是controller的註釋，記得修改

然後F5 執行，都加上了，感覺前端大佬再也不會說看不懂介面了，哈哈哈哈

接下來開始第三個問題：新增實體類說明註釋

新建一個.net core 類庫Blog.Core.Model，注意是 .net core的類庫

新建一個Love的實體類

    /// <summary>
    /// 這是愛
    /// </summary>
    public class Love
    {
        /// <summary>
        /// id
        /// </summary>
        public int Id { get; set; }
        /// <summary>
        /// 姓名
        /// </summary>
        public string Name { get; set; }
        /// <summary>
        /// 年齡
        /// </summary>
        public int Age { get; set; }
    }

然後就是剛新增的類庫中，在Model層專案，屬性，中新增xml路徑，添加註釋（這裡的步驟和API專案的新增方法一致，不會的請留言），然後在API專案中新增引用
image

改寫注入方法，並在控制器中引數引用

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

            #region Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v0.1.0",
                    Title = "Blog.Core API",
                    Description = "框架說明文件",
                    TermsOfService = "None",
                    Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "Blog.Core", Email = "[email protected]", Url = "https://www.jianshu.com/u/94102b59cc2a" }
                });
                //就是這裡

                var basePath = Microsoft.DotNet.PlatformAbstractions.ApplicationEnvironment.ApplicationBasePath;
                var xmlPath = Path.Combine(basePath, "Blog.Core.xml");//這個就是剛剛配置的xml檔名
                c.IncludeXmlComments(xmlPath, true);//預設的第二個引數是false，這個是controller的註釋，記得修改

                var xmlModelPath = Path.Combine(basePath, "Blog.Core.Model.xml");//這個就是Model層的xml檔名
                
                c.IncludeXmlComments(xmlModelPath);

            });

            #endregion

        }

  　　　/// <summary>
       /// post
       /// </summary>
       /// <param name="love">model實體類引數</param>
        [HttpPost]
        public void Post(Love love)
        {
        }

• .net core 2.1 新不同

注意，不能再HttpGet中，用實體類做引數，會報錯

dang dang dang，就出來了

• .net core 2.1 新不同

NEXT

對於介面是如何加許可權驗證的？

讓我們帶著這些問題，繼續瀏覽下一篇吧，Swagger 3.3 許可權

CODE