欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  IT编程

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

程序员文章站 2022-06-21 17:04:20
Asp.Net Core中使用Swagger,你不得不踩的坑 ......

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

 这篇文章着重讲几点:

  • swagger 跨层注释问题
  • swagger Get请求传多个参数的问题
  • swagger Enum 注释问题
  • swagger api文档版本控制

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

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

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

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

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

 

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

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

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

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

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

 

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

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

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

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

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

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

 

这两个包是做版本控制管理的,如果不需要可以不添加,这里我做演示就添加上,额外再引入一个包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 = 0,
        /// <summary>
        /// 线下交易
        /// </summary>
        [Description("线下交易")]
        StoreTrade = 1,

    }
}

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

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

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

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

github地址:

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

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

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