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 = 0,
        /// <summary>
        /// 線下交易
        /// </summary>
        [Description("線下交易")]
        StoreTrade = 1,

    }
}

 效果圖如下:**我把model和enum寫到一個文件里,如果分別跨層寫的話,也沒有什么問題,只需要在startp里配置一下,由於時間關系,源碼我上傳到我都github,就不再細分了

 

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

如果您認為這篇文章還不錯或者有所收獲,您可以點擊右下角的【推薦】按鈕精神支持,因為這種支持是我繼續寫作,分享的最大動力

歡迎大家關注我都我的微信 公眾號,公眾號漲粉絲人數,就是你們對我的喜愛程度!

 

 


注意!

本站转载的文章为个人学习借鉴使用,本站对版权不负任何法律责任。如果侵犯了您的隐私权益,请联系我们删除。



 
粤ICP备14056181号  © 2014-2021 ITdaan.com