.NET core 使用Swagger

時間 2020-07-21

標籤 core 使用 swagger 简体版

原文原文鏈接

一爲何使用swagger

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

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

2.一站式服務，只須要訪問swagger的地址，就能夠看到全部的後臺接口和功能，而且能測試接口狀態，真正是完全的先後端分離了。後端

3.內嵌調試，能夠查看接口狀態和返回值結果很方便。api

思考：若是能在把請求日誌也集成進去就更好了。框架

二開始一步一步搭建swagger

第一步：建立一個.NET CORE的web項目（vs2019）前後端分離

到這兒一個.NET core webapi就建立完成了，下面咱們進行swagger的引用和使用。函數

第二步：使用Swagger 工具

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

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

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

包引入完成後，下一步就是須要註冊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);
        }