[Abp vNext 入坑分享] - 6.完整接入swagger

前言

因爲最近一直在修改一下排版，同時找了非技術的朋友幫忙看一下排版的問題，如今已經基本上肯定了排版和樣式了。更新能夠恢復正常了。
做爲一個寫前端代碼基本只寫js不寫css的開發，搞排版真的頭疼。。各位將就着看吧！！排版並不會過高大上，主要是保證了閱讀體驗，讓各位儘可能不會看得頭暈眼花而錯過了比較重要的內容。但願各位有收穫吧！而後後面我會找個時間把以前的文章再從新排版一下。。

簡要說明

【項目源碼】

【章節目錄】
本文主要是介紹如何接入swagger來自動生成api文檔。【Swagger介紹】
首先咱們須要知道的是swagger是能夠經過xml的格式來進行生成相關的接口文檔的，其次VS是能夠根據代碼的註釋進行生成相應的xml的。所以咱們能夠藉助VS的xml文件使swagger生成相關的文檔。

再而後一點就是咱們要肯定咱們須要生成文檔的項目。根據以前的介紹咱們知道咱們能夠對外輸出的項目一個是api是用於接口的；另外一個就是application.contract，這個項目主要定義了入參與出參的dto是能夠對外輸出的。因此咱們須要生成swagger的項目就只有這兩個。具體步驟以下：

具體步驟

一、選中AbpVnext.Learn.HttpApi項目-》右鍵-》屬性-》生成；而後以下配置輸出xml文檔

二、而後生成項目，若此項目中存在標準的註釋，則會生成相應的xml文件，以下所示：

三、而後右鍵此xml文件-》屬性-》始終複製；Application.Contracts項目重複以上的操做

四、在LearnHttpApiHostModule找到原來的AddSwaggerGen方法，修改成如下的形式，而後調試項目：

context.Services.AddSwaggerGen(
                options =>
                {
                    options.SwaggerDoc("v1", new OpenApiInfo { Title = "Learn API", Version = "v1" });
                    options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
                    {
                        Description = "JWT受權(數據將在請求頭中進行傳輸) 直接在下框中輸入Bearer {token}（注意二者之間是一個空格）\"",
                        Name = "Authorization",//jwt默認的參數名稱
                        In = ParameterLocation.Header,//jwt默認存放Authorization信息的位置(請求頭中)
                        Type = SecuritySchemeType.ApiKey
                    });
                    options.AddSecurityRequirement(new OpenApiSecurityRequirement
                    {
                        { new OpenApiSecurityScheme
                        {
                            Reference = new OpenApiReference()
                            {
                                Id = "Bearer",
                                Type = ReferenceType.SecurityScheme
                            }
                        }, Array.Empty<string>() }
                    });
                    var xmlapipath = Path.Combine(AppContext.BaseDirectory, "AbpVnext.Learn.HttpApi.xml");
                    if (File.Exists(xmlapipath))
                    {
                        options.IncludeXmlComments(xmlapipath);
                    }
                    var xmlapppath = Path.Combine(AppContext.BaseDirectory, "AbpVnext.Learn.Application.Contracts.xml");
                    if (File.Exists(xmlapipath))
                    {
                        options.IncludeXmlComments(xmlapppath);
                    }
                });

如今咱們能夠看到相應的api與入參，出參的dto都已經生成成功了，可是還有一點不太滿意的是LoginOutputDto沒有輸出來。因爲咱們的ResultModel的data是一個object，因此對swagger來講，至關於沒有使用的LoginOutputDto則不輸出此Dto的文檔。所以咱們須要進一步優化，使用泛型來規劃輸出的參數，而不使用object這類弱類型

五、修改ResultModel爲ResultModel ,以下：

public class ResultModel<T>
    {
        public ResultModel(int _code,string _msg,T _data)
        {
            code = _code;
            msg = _msg;
            data = _data;
        }
        /// <summary>
        /// 0爲成功，其它爲失敗
        /// </summary>
        public int code  { get; set; }
        public string msg { get; set; }
        public T data { get; set; }
    }

修改登陸的接口的代碼，以下圖，

再次調試項目，以下圖所示，咱們的出參dto也生成出來了，並且因爲咱們在接口裏面很清晰的描
述了入參是哪一個dto，出參是哪一個dto，在與前端或客戶端同事聯調的時候並不須要輸出太多內容，
只要說是哪一個接口就好了，而後他就能夠去找相應的接口與dto了。

六、而後，咱們能夠看到，token的Auth的按鈕也顯示在了頁面上

接下來咱們試一下這個功能是否完善了。首先咱們在Base的LearnController中添加如下代碼，用於獲取用戶的登陸id

/// <summary>
        /// 登陸用戶的用戶id
        /// </summary>
        protected string userid
        {
            get { return HttpContext.User.Identity.IsAuthenticated ? HttpContext.User.FindFirst(ClaimTypes.NameIdentifier).Value : ""; }
        }

而後咱們在UserController中添加如下代碼來獲取User信息：

[HttpPost]
        [Route("init")]
        [Authorize]
        public async Task<ResultModel<UserDto>> Init()
        {
            var user =await _userAppServices.get_userbyuserid(new Guid(userid));
            return new ResultModel<UserDto>(200, "", user);
        }

而後調試項目，點擊Authorize---》輸入Login接口獲取到的token--》Authorize，以下圖

測試user/init接口，以下圖，表示咱們的token的受權與解析相應的用戶id是正常的

最後有一點要注意的是,因爲xml文件你們都是使用的同同樣的，所以建議是不能簽入的，應該是加入ignorelist裏面，由jenkins/gitlab等自動打包的工具進行生成統一的xml，開發人員只要進行代碼相關的簽入就好了。

下一章介紹

Auttomapper與validation的使用方法，這裏使用的是官方的validation來進行校驗。雖然FluentValidation更增強大，可是我的以爲validation已經能知足絕大部分需求了，若是有進一步的判斷，能夠直接寫有controller裏面，不必爲了很小一部分的需求而引入一個更復雜的組件。這個各位能夠根據本身的需求進行判斷