.NET core 使用Swagger

一 為什麼使用swagger

swagger是一種API文檔管理的框架

1.可以在代碼中添加註釋，且自動生成API文檔，無需再次編寫，友好的界面讓API文檔更易懂。

2.一站式服務，只需要訪問swagger的地址，就可以看到所有的後臺介面和功能，並且能測試介面狀態，真正是徹底的前後端分離了。

3.內嵌調試，可以查看介面狀態和返回值結果很方便。

思考：如果能在把請求日誌也集成進去就更好了。

二 開始一步一步搭建swagger

第一步：創建一個.NET CORE的web項目（vs2019）

 到這兒一個.NET core webapi就創建完成了，下麵我們進行swagger的引用和使用。

第二步：使用Swagger 

選擇項目右鍵單擊管理nuget包

 打開之後，選擇瀏覽輸入 Swashbuckle.AspNetCore ，選擇後安裝

然後依次點擊確定和接受，就算安裝完成了。安裝完成後，依賴項裡面就會多出來一個包的引用。

 包引入完成後，下一步就是需要註冊Swagger了，這裡我們可以創建一個類來存放註冊的信息（代碼會整潔，邏輯也會清晰一點），首先新建一個文件夾名字隨便取，在新建一個Swagger類。

 需要引用 

using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace WebApi.Core.Api.SetUpService
{
    public static class SwaggerSetUp
    {
        public static void AddSwaggerSetup(this IServiceCollection services)
        {
            if (services == null) throw new ArgumentNullException(nameof(services));

            var ApiName = "Webapi.Core";

            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("V1", new OpenApiInfo
                {
                    // {ApiName} 定義成全局變數，方便修改
                    Version = "V1",
                    Title = $"{ApiName} 介面文檔——Netcore 3.0",
                    Description = $"{ApiName} HTTP API V1",

                });
                c.OrderActionsBy(o => o.RelativePath);
            });

        }
    }
}

接下來就是需要到 Startup 類，找到ConfigureServices 註冊我們寫好的服務，可以把游標放在AddSwaggerSetup按12，就會跳轉到我們寫的SwaggerSetUp方法中。

 接著在StartUp類中找到Configure方法編輯，這裡面RoutePrefix 就是你需要訪問的url路徑後面的路由比如 我們訪問 localhost:8080/ApiDoc就可以跳轉到Swagger的頁面

 我們把IIS 啟動的註釋，項目啟動的Url改成根目錄

修改後按F5啟動項目，沒有找到

接下來我們輸入/ApiDoc敲回車，就可以了，這就是配置 RoutePrefix 屬性的作用。

 我們找到Startup中的Configure把RoutePrefix 設置為空再按F5啟動，直接根目錄打開就進入了Swagger頁面中。

 接下來我們實際使用一下，先把自帶的Controller刪除，然後創建一個BaseController繼承ControllerBase ，右鍵Controllers選擇添加-控制器，選一個空的控制器，取名字

 BaseController是一個基類，目的是為了自定義路由，然後放一些公共的方法，這樣你每次新建一個類就只需要繼承BaseController類無需做太多重覆工作了

 接下來我們創建一個UserController，創建方式如同上面的，把這兩個地方修改一下

 添加代碼

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;

namespace WebApi.Core.Api.Controllers
{
    public class UsersController : BaseController
    {
        [HttpGet]
        public IActionResult Hello()
        {
            return Ok("Hello World");
        }
    }
}

F5啟動，這樣一個簡單的Swagger就已經搭建完成。但是比較簡單，功能也不是很多

 下麵繼續在Swagger下麵添加一些東西。文檔註釋，我們新建一個Model類庫，因為Swagger不僅可以把介面註釋顯示，也可以對實體進行註釋的顯示。

右鍵解決方案->添加->新建項目->選擇類庫->創建類庫

 右鍵項目->屬性->生成  WebApi.Core.Model 也同樣操作

 XML文件放在同一個位置方便管理

配置好了XML，接下來要關聯這個配置 編輯 SwaggerSetUp.cs類 找到 AddSwaggerSetup函數，添加XML關聯代碼

 public static void AddSwaggerSetup(this IServiceCollection services)
        {
            if (services == null) throw new ArgumentNullException(nameof(services));

            var ApiName = "Webapi.Core";

            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("V1", new OpenApiInfo
                {
                    // {ApiName} 定義成全局變數，方便修改
                    Version = "V1",
                    Title = $"{ApiName} 介面文檔——Netcore 3.0",
                    Description = $"{ApiName} HTTP API V1",

                });
                c.OrderActionsBy(o => o.RelativePath);

                // 獲取xml註釋文件的目錄
                var xmlPath = Path.Combine(AppContext.BaseDirectory, "WebApi.Core.Api.xml");
                c.IncludeXmlComments(xmlPath, true);//預設的第二個參數是false，這個是controller的註釋，記得修改

                // 獲取xml註釋文件的目錄
                var xmlPathModel = Path.Combine(AppContext.BaseDirectory, "WebApi.Core.Model.xml");
                c.IncludeXmlComments(xmlPath, true);//預設的第二個參數是false，這個是controller的註釋，記得修改

            });

        }

下麵在model類庫中添加一個類UsersModel  寫好全部的註釋

 接下來在UsersController 添加函數來驗證 註釋是否有效

 這裡我們加了註釋，啟動F5 看看效果，從下麵的圖片看，是沒問題的註釋已經顯示出來了，但是model在哪裡，為什麼沒有顯示出來

 我們在UsersController 添加如下函數

/// <summary>
        /// 用戶實體類測試
        /// </summary>
        /// <param name="usersModel"></param>
        /// <returns></returns>
        [HttpPost]
        public IActionResult UsersTestSwagger(UsersModel usersModel)
        {
            return Ok(usersModel);
        }

然後F5啟動，這裡我們看到 model類 顯示出來了，但是沒有註釋為什麼呢

經過排查發現SwaggerSetUp類中的AddSwaggerSetup 函數裡面有一段代碼寫錯了，因為複製粘貼的問題，這種問題我們經常會犯，所以如果可以，以後儘量不要複製粘貼，還能加深你敲代碼的能力。

 改好之後 重新F5 ，已經把model類裡面的註釋也顯示出來了，

 如果我們不想在Swagger 裡面顯示出來  那就可以在函數上面加一個特性 [ApiExplorerSettings(IgnoreApi = true)]

 可以看到 Hello 這個函數就被隱藏了

 到此，.net core 搭建和使用Swagger就算完成了，是不是很簡單。

下麵在簡單介紹一下，請求和響應應該怎麼去看

 我們單擊try it out

我們編輯好參數，單擊Execute按鈕，可以看到請求一個json串，並且把這個json串原樣輸出了，這在以前需要藉助工具來完成，現在直接在啟動的程式上就可以查看你的介面寫的是否正確，或者哪裡有問題了