介紹

https://github.com/domaindrivendev/Swashbuckle.AspNetCore

https://github.com/swagger-api/swagger-ui

整合swagger

引用Swashbuckle

新建一個restfull api專案，版本為.NET CORE 3.1，
使用nuget新增Swashbuckle.AspNetCore,當前版本為6.2.2

新增並配置 Swagger 中介軟體

修改Startup類的ConfigureServices方法

//註冊Swagger生成器，定義一個和多個Swagger 文件
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});
 

Configure方法

//啟用中介軟體服務生成Swagger作為JSON終結點
app.UseSwagger();
//啟用中介軟體服務對swagger-ui，指定Swagger JSON終結點
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

到此配置結束，啟動應用，訪問http://localhost:/swagger/index.html檢視

新增介面說明

啟用XML註釋：
右鍵單擊“解決方案資源管理器”中的專案，然後選擇“屬性”,
檢視“生成”選項卡的“輸出”部分下的“XML 文件檔案”框勾選上

修改Startup類的ConfigureServices方法

app.UseSwaggerUI(c =>
{
    .....此處省略
  var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
  var xmlPath = Path.Combine(basePath, "SwaggerApi.xml");
  c.IncludeXmlComments(xmlPath);
});

在方法上註釋

/// <summary>
/// Get方法
/// </summary>
/// <returns></returns>
 

參考文件

https://cloud.tencent.com/developer/article/1339371
https://www.cnblogs.com/yilezhu/p/9241261.html

ABP整合MagicodesSwagger

環境

.NET CORE 3.1.0

配置檔案

appsettings.json增加節點

  "SwaggerDoc": {
    "IsEnabled": "true",
    //將列舉值以字串顯示
    "DescribeAllEnumsAsStrings": false,
    "SwaggerDocInfos": [
      {
        "IsEnabled": "true",
        "Title": "管理平臺 API文件",
        "Version": "v1",
        "GroupName": "admin",
        "Description": "",
        "GroupUrlPrefix": "admin/"
      }
    ],
    "HiddenApi": {
      "IsEnabled": "true",
      "Urls": [
        { "Url": "app1/Values/{id}" }
      ]
    },
    "UseFullNameForSchemaId": "false"
  }

Startup.cs

 public IServiceProvider ConfigureServices(IServiceCollection services)
        { 
            ......此處省略
            //線上釋出版,不配置
            if (!_environment.IsProduction())
            {
                services.AddMagicodesSwaggerGen(_appConfig);
                services.AddSwaggerGen(options =>
                {
                    options.CustomSchemaIds(r => r.FullName);
                    //options.DocumentFilter<ApplyTagDescriptions>();//模組說明 
                }); 
            }
			
		 return services.AddAbp<ECMWebModule>(options =>
            {
                //Configure Log4Net logging
                options.IocManager.IocContainer.AddFacility<LoggingFacility>(
                   f => f.UseAbpLog4Net().WithConfig("log4net.config")
               );
            }, 0);
            //return services.BuildServiceProvider();
        }
		
        /// <summary>
        /// 負責http請求管道的配置
        /// </summary>
        public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory, IWebHostEnvironment env)
        { 
            ......此處省略
            //線上釋出版,不配置 ==> 一定要放在app.UseStaticFiles();之前，否則會出錯
            if (!env.IsProduction())
            {
                app.UseMagicodesSwaggerUI(_appConfig, (options, config) =>
                {
                    options.RoutePrefix = string.Empty;
                    options.ShowExtensions();
                    options.EnableValidator();
                    // 將選擇的介面地址連線到URL，方便與他人定位
                    //options.EnableDeepLinking();
                    // 啟用過濾器（大小寫敏感）
                    options.EnableFilter();
                    // 展開級別
                    //options.DocExpansion(Swashbuckle.AspNetCore.SwaggerUI.DocExpansion.None);
                    // 右側顯示方法名
                    //options.DisplayOperationId();

                    /* 啟用下面程式碼，生成適合用於對接的Swagger頁面 */
                    // 預設顯示model
                    //options.DefaultModelRendering(Swashbuckle.AspNetCore.SwaggerUI.ModelRendering.Model);
                    // 模型展開到2級
                    options.DefaultModelExpandDepth(3);
                    // 隱藏model列表
                    //options.DefaultModelsExpandDepth(-1);
                    // 隱藏 [Try it]
                    //options.SupportedSubmitMethods();
                });
            }
 
            app.UseStaticFiles();
            ......此處省略

        }