.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);
        }