Asp.Net Core中使用Swagger，你不得不踩的坑

　　很久不来写blog了，换了新工作后很累，很忙。每天常态化加班到21点，偶尔还会到凌晨，加班很累，但这段时间，也确实学到了不少知识，今天这篇文章和大家分享一下：Asp.Net Core中使用Swagger，你不得不踩的坑.

　这篇文章着重讲几点：

swagger 跨层注释问题

swagger Get请求传多个参数的问题

swagger Enum 注释问题

swagger api文档版本控制

第一步：搭建一个webapi项目或者mvc项目，引入swagger nuget

我创建项目，习惯性的先创建一个解决方案，取名为TB.AspNetCore.Swagger

接着会在解决方案上新建项目，取名TB.AspNetCore.Swagger.SApi，然后选择webapi,https最好去掉，加上后提示你要证书什么的，还会提示你网站不安全，我们做测试，没必要勾选

为了本项目问题的说明，我们会继续在常见三个类库项目TB.AspNetCore.Swagger.Data 放数据库实体，TB.AspNetCore.Swagger.Model 放模型-ViewModel，TB.AspNetCore.Swagger.Enum 放枚举类型

删除项目默认生成的class和controller，在api项目上引入swagger的nuget包，搜索：Swashbuckle.AspNetCore，这个包就在持续更新速度很快，已经到了3.0

第二部：引入版本控制nuget，添加关键性配置代码

这两个包是做版本控制管理的，如果不需要可以不添加，这里我做演示就添加上，额外再引入一个包Microsoft.Extensions.PlatformAbstractions，这个包是获取一些系统配置路径变量的包，这个包实在鸡肋,没有注释。。添加部分关键代码在configuration和configurationservice，代码如下：

services.AddSwaggerGen(

                options =>

                {

                    // resolve the IApiVersionDescriptionProvider service

                    // note: that we have to build a temporary service provider here because one has not been created yet

                    var provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();

                    // add a swagger document for each discovered API version

                    // note: you might choose to skip or document deprecated API versions differently

                    foreach (var description in provider.ApiVersionDescriptions)

                    {

                        options.SwaggerDoc(description.GroupName, CreateInfoForApiVersion(description));

                    }

                    // add a custom operation filter which sets default values

                    options.OperationFilter<SwaggerDefaultValues>();

                    //

                    // integrate xml comments

                    options.IncludeXmlComments(XmlCommentsFilePath);

                    options.IncludeXmlComments(XmlModelsFilePath);

                });

public void Configure(IApplicationBuilder app, IHostingEnvironment env, IApiVersionDescriptionProvider provider)

        {

            if (env.IsDevelopment())

            {

                app.UseDeveloperExceptionPage();

            }

            app.UseMvc();

            //Swagger

            app.UseSwagger();

            app.UseSwaggerUI(

                options =>

                {

                    foreach (var description in provider.ApiVersionDescriptions)

                    {

                        options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());

                    }

                });

        }

第三部：新建控制器，测试我们的项目

我做了一个订单查询控制器，一个提交订单，一个查询订单，查询订单为get请求多参数，提交订单为post请求，其中的备注设计到枚举类型的如何加载

代码如下：

namespace TB.AspNetCore.Swagger.SApi.Controllers

{

    [Produces("application/json")]

    [ApiVersion("1.0", Deprecated = false)]

    [Route("api/v{api-version:apiVersion}/[controller]/[action]")]

    [ApiController]

    public class OrderController : ControllerBase

    {

        /// <summary>

        /// 查询订单

        /// </summary>

        /// <param name="orderCode">订单号</param>

        /// <param name="orderName">订单名称</param>

        /// <returns></returns>

        [HttpGet("{orderCode}/{orderName}")]

        public OrderModel QueryOrder(string orderCode, string orderName)

        {

            OrderModel model = new OrderModel

            {

                OrderCode = orderCode

            };

            return model;

        }

        /// <summary>

        /// 提交订单

        /// </summary>

        /// <param name="model"></param>

        /// <returns></returns>

        [HttpPost]

        public OrderModel SubOrder([FromBody]OrderModel model)

        {

            return model;

        }

    }

    public class OrderModel

    {

        /// <summary>

        /// 订单号

        /// </summary>

        public string OrderCode { get; set; }

        /// <summary>

        /// 订单金额

        /// </summary>

        public decimal OrderAmount { get; set; }

        /// <summary>

        /// 订单类型

        /// <Remark>

        /// 0 商家入驻

        /// 1 线下交易

        /// </Remark>

        /// </summary>

        public OrderTypeInfo OrderType { get; set; }

    }

    /// <summary>

    ///

    /// </summary>

    public enum OrderTypeInfo

    {

        /// <summary>

        /// 商家入驻

        /// </summary>

        [Description("商家入驻")]

        StoreEntry = ,

        /// <summary>

        /// 线下交易

        /// </summary>

        [Description("线下交易")]

        StoreTrade = ,

    }

}

效果图如下：**我把model和enum写到一个文件里，如果分别跨层写的话，也没有什么问题，只需要在startp里配置一下，由于时间关系，源码我上传到我都github，就不再细分了

github地址:https://github.com/TopGuo/TB.AspNetCore.Swagger

如果您认为这篇文章还不错或者有所收获，您可以点击右下角的【推荐】按钮精神支持，因为这种支持是我继续写作，分享的最大动力

欢迎大家关注我都我的微信公众号，公众号涨粉丝人数，就是你们对我的喜爱程度！

巴特西

Asp.Net Core中使用Swagger，你不得不踩的坑

最新文章

热门文章