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

二B方案程式設計師發表於2020-05-18

前言

由於最近一直在修改一下排版,同時找了非技術的朋友幫忙看一下排版的問題,現在已經基本上確定了排版和樣式了。更新可以恢復正常了。
作為一個寫前端程式碼基本只寫js不寫css的開發,搞排版真的頭疼。。各位將就著看吧!!排版並不會太高大上,主要是保證了閱讀體驗,讓各位儘量不會看得頭暈眼花而錯過了比較重要的內容。希望各位有收穫吧!然後後面我會找個時間把之前的文章再重新排版一下。。

簡要說明

【專案原始碼】

【章節目錄】
本文主要是介紹如何接入swagger來自動生成api文件。【Swagger介紹】
首先我們需要知道的是swagger是可以通過xml的格式來進行生成相關的介面文件的,其次VS是可以根據程式碼的註釋進行生成相應的xml的。因此我們可以藉助VS的xml檔案使swagger生成相關的文件。

再然後一點就是我們要確定我們需要生成文件的專案。根據之前的介紹我們知道我們可以對外輸出的專案一個是api是用於介面的;另一個就是application.contract,這個專案主要定義了入參與出參的dto是可以對外輸出的。所以我們需要生成swagger的專案就只有這兩個。具體步驟如下:

具體步驟

1、選中AbpVnext.Learn.HttpApi專案-》右鍵-》屬性-》生成;然後如下配置輸出xml文件

2、然後生成專案,若此專案中存在標準的註釋,則會生成相應的xml檔案,如下所示:

3、然後右鍵此xml檔案-》屬性-》始終複製;Application.Contracts專案重複以上的操作

4、在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這類弱型別

5、修改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了。

6、然後,我們可以看到,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裡面,沒必要為了很小一部分的需求而引入一個更復雜的元件。這個各位可以根據自己的需求進行判斷

相關文章