從壹開始先後端分離【 .NET Core2.0/3.0 +Vue2.0 】框架之四 || Swagger的使用 3.2

本文3.0版本文章

https://mp.weixin.qq.com/s/SHNNQoYF-t8i2j85E1oSYA

 

 

前言

若是想直接在域名的根目錄直接加載 swagger 好比訪問：localhost:8001 就能訪問，能夠這樣設置：

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");
    c.RoutePrefix = "";//路徑配置，設置爲空，表示直接訪問該文件，
 //路徑配置，設置爲空，表示直接在根域名（localhost:8001）訪問該文件,注意localhost:8001/swagger是訪問不到的，
 //這個時候去launchSettings.json中把"launchUrl": "swagger/index.html"去掉， 而後直接訪問localhost:8001/index.html便可

});

 

 

書接上文《從零開始搭建本身的先後端分離【 .NET Core2.0 Api + Vue 2.0 】框架之三 || Swagger的使用 3.1》，上文中只是簡單的對如何使用Swagger做了介紹，並且最後也提出了幾個問題，這裏再重溫下那幾個問題：

爲什麼直接 F5 運行，首頁仍是沒法加載？

接口雖有，可是卻沒有相應的文字說明？

項目開發中的實體類是如何在Swagger中展現的？

對於接口是如何加權限驗證的？

 

1、swagger的通常用法

0、設置swagger頁面爲首頁——開發環境

在上一回中咱們提到，咱們直接F5運行項目，出現了系統默認頁，

 

雖然能夠在輸入/swagger後，順利的訪問swagger ui頁，可是咱們發現每次運行項目，都會默認訪問api/values這個接口，我想要將啓動頁設爲swagger（或者是任意一個頁面），你就須要用到了

**設置文件launchSettings.json **了：

 

 

而後你再一次F5 運行，就會發現不同了，其餘的配置，以及之後部署中的設置，咱們會在之後的文章中都有提到。

 

一、設置默認直接首頁訪問 —— 生產環境

上邊的方法很正常，直接這麼運行，就能夠了，可是若是咱們部署到服務器，就會發現，上邊的那種默認啓動首頁無效了，仍是須要咱們每次手動在域名後邊輸入 /swagger ，麻煩！

別慌，swagger 給咱們提供了這個擴展，咱們能夠指定一個空字符，做爲 swagger 的地址，在Configure中配置中間件：

 app.UseSwagger();
 app.UseSwaggerUI(c =>
 {
     c.SwaggerEndpoint($"/swagger/v1/swagger.json", $"{ApiName} v1");//注意這個 v1 要和上邊 ConfigureServices 中配置的大小寫一致 // 將swagger設置成首頁
     c.RoutePrefix = ""; //路徑配置，設置爲空，表示直接在根域名（localhost:8001）訪問該文件,注意localhost:8001/swagger是訪問不到的，去launchSettings.json把launchUrl去掉
 });

 

 

 而後再把咱們上邊的項目文件 launchSettings.json 的 launchUrl 給去掉就好了，這樣咱們不管是本地開發環境，仍是生產環境，均可以默認首頁加載了。

好比個人在線地址 ：http://123.206.33.109:8081

 

二、爲接口添加註釋

接下來，咱們就須要解決第二個問題，如何增長文字說明，就是傳說中的註釋：

右鍵項目名稱=>屬性=>生成，勾選「輸出」下面的「xml文檔文件」，系統會默認生成一個，固然老規矩，你也能夠本身起一個名字：

這裏我用的是相對路徑，能夠直接生成到 api 層的 bin文件夾下

 

 

 

這個時候，先別忙着運行項目，做爲老司機的我，只要是改代碼或者配置文件，保存後，第一件事就是看看有沒有錯誤，一看，咦~~~果真，雖然是警告，能夠強迫症呀，一看還挺多

 

 

別慌！一看，哦！原來是swagger把一些接口方法都經過xml文件配置了，就是剛剛上文提到的，因此咱們只須要加上方法註釋就能夠辣，能夠左斜槓/，連續三下便可

 

若是你不想每個方法都這麼加註釋，能夠這麼配置（對當前項目進行配置，能夠忽略警告，記得在後邊加上分號 ;1591）：

 

 

如今呢，配置好了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 = "Blog.Core@xxx.com", 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 新不一樣 感謝網友反饋@風格不一樣，@dannyjyc
• 獲取項目路徑的方式和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 運行，都加上了，感受前端大佬不再會說看不懂接口了，哈哈哈哈

 

三、對 Model 也添加註釋說明

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

 

新建一個.net core 類庫Blog.Core.Model，注意是 .net core的類庫，或者使用標準庫也是能夠的！（標準庫能夠在 NetCore 和 Framework 兩個項目均可以跑）

 

 

新建一個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; }
    }

 

這裏如今有兩個狀況，或者說是兩個操做方案：

 

一、當前 api 層直接引用了 Blog.Core.Model 層；

 

這個時候，咱們只須要配置仿照上邊 api 層配置的xml文檔那樣，在 Blog.Core.Model 層的 XML 輸出到 API 層就好了：

 

二、API 層沒有直接引用 Model 層，而是經過級聯的形式；

就好比個人 Github 上的代碼那樣：

 效果和上邊是同樣的，也算是引用 Model 層了。

 

 

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

配置xml文檔

 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 = "Blog.Core@xxx.com", 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)
        {
        }

 

dang dang dang，就出來了

 

 

 

五、去掉Swagger警告提示

在Model層中，咱們創建了不少實體，若是你沒有爲每個實體都添加註釋的話，可能會出現這樣的警告：

若是有的小夥伴，不想添加註釋，而又不想看到這個強迫症的警告提示，那就能夠這麼作，

右鍵項目 屬性 -》 Errors and warnings 配置 1591：

 

 

六、隱藏某些接口

若是不想顯示某些接口，直接在controller 上，或者action 上，增長特性

[ApiExplorerSettings(IgnoreApi = true)]

 

 

 

 

2、結語

對於接口是如何加權限驗證的？

讓咱們帶着這些問題，繼續瀏覽下一篇吧，Swagger 3.3 JWT 權限，必看篇。

 

 

3、Github && Gitee

https://github.com/anjoy8/Blog.Core.git

https://gitee.com/laozhangIsPhi/Blog.Core