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

時間 2019-11-05

標籤 asp.net asp core 使用 swagger 不得不欄目 ASP 简体版

原文原文鏈接

　　好久不來寫blog了，換了新工做後很累，很忙。天天常態化加班到21點，偶爾還會到凌晨，加班很累，但這段時間，也確實學到了很多知識，今天這篇文章和你們分享一下：Asp.Net Core中使用Swagger，你不得不踩的坑.git

　這篇文章着重講幾點：github

swagger 跨層註釋問題

swagger Get請求傳多個參數的問題

swagger Enum 註釋問題

swagger api文檔版本控制

第一步：搭建一個webapi項目或者mvc項目，引入swagger nugetweb

我建立項目，習慣性的先建立一個解決方案，取名爲TB.AspNetCore.Swagger數據庫

接着會在解決方案上新建項目，取名TB.AspNetCore.Swagger.SApi，而後選擇webapi,https最好去掉，加上後提示你要證書什麼的，還會提示你網站不安全，咱們作測試，不必勾選json

爲了本項目問題的說明，咱們會繼續在常見三個類庫項目TB.AspNetCore.Swagger.Data 放數據庫實體，TB.AspNetCore.Swagger.Model 放模型-ViewModel，TB.AspNetCore.Swagger.Enum 放枚舉類型api

刪除項目默認生成的class和controller，在api項目上引入swagger的nuget包，搜索：Swashbuckle.AspNetCore，這個包就在持續更新速度很快，已經到了3.0安全

第二部：引入版本控制nuget，添加關鍵性配置代碼微信

這兩個包是作版本控制管理的，若是不須要能夠不添加，這裏我作演示就添加上，額外再引入一個包Microsoft.Extensions.PlatformAbstractions，這個包是獲取一些系統配置路徑變量的包，這個包實在雞肋,沒有註釋。。添加部分關鍵代碼在configuration和configurationservice，代碼以下：mvc

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());
                    }
                });
        }

第三部：新建控制器，測試咱們的項目app

我作了一個訂單查詢控制器，一個提交訂單，一個查詢訂單，查詢訂單爲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,

    }
}