.NET core 使用Swagger

本文轉載自查看原文 2020-07-20 13:21 1414 搭建.NET core webApi項目

一為什么使用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);
        }