[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里面，不必为了很小一部分的需求而引入一个更复杂的组件。这个各位能够根据本身的需求进行判断