wagger 是一個規范且完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。
Swagger 的目標是對 REST API 定義一個標準且和語言無關的接口，可以讓人和計算機擁有無需訪問源碼、文檔或網絡流量監測就可以發現和理解服務的能力。當通過 Swagger 進行正確定義，用戶可以理解遠程服務并使用最少實現邏輯與遠程服務進行交互。與為底層編程所實現的接口類似，Swagger 消除了調用服務時可能會有的猜測。

Swagger 的優勢

• 支持 API 自動生成同步的在線文檔：使用 Swagger 后者可以直接通過代碼生成文檔，不再需要自己手動編寫接口文檔了，對程序員來說非常方便，可以節約寫文檔的時間去學習新技術。
• 提供 Web 頁面在線測試 API：光有文檔還不夠，Swagger 生成的文檔還支持在線測試。參數和格式都定好了，直接在界面上輸入參數對應的值即可在線測試接口。

實戰演示

1、新建一個asp.net core web api項目

2、Nuget安裝Swagger

3、為接口及接口中用到的類添加注釋

4、右鍵項目屬性（如果項目中有其他庫的，都需要參照配置下）生成XML文檔，如下圖打勾保存

5、Startup配置Swagger，這里用到了一個自定義的擴展類：SwaggerHttpHeaderOperation，這個類里面增加了調試的Http請求header參數，比如Token就可以擴展下，這樣在調試時就可以填寫該參數，方便調試需要鑒權的接口。

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using System;
using System.IO;
using System.Text;

namespace ZQSwaggerDemo
{
    public class Startup
    {
        const string PROJECTNAME = "知擎物聯API";
        const string VERSION = "v1.0.0";

        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            //配置swagger
            StringBuilder fDescription = new StringBuilder();
            fDescription.Append("<a target='_blank' href='https://www.yyzq.net' class='link'>常州知擎物聯科技有限公司 版權所有</a>");
            fDescription.Append($"<br>API適用標注說明：");
            fDescription.Append($"<br><span style='color:blue'>【NOTOKEN】</span>：無需登錄可訪問");
            services.AddSwaggerGen(c =>
            {
                c.OperationFilter<SwaggerHttpHeaderOperation>();

                c.SwaggerDoc(VERSION, new Microsoft.OpenApi.Models.OpenApiInfo()
                {
                    Title = PROJECTNAME,
                    Version = VERSION,
                    Description = ""
                }); ;
                //加載注釋xml文件（這里演示的代碼是為了方便一次性加載多個XML文檔，省去了一個個XML文件添加的繁瑣）
                string[] files = Directory.GetFiles(AppDomain.CurrentDomain.BaseDirectory, "ZQ*.xml");
                foreach (string item in files)
                {
                    c.IncludeXmlComments(item);
                }
            });
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            app.UseSwagger();//啟用中間件服務生成Swagger作為JSON終結點
            app.UseSwaggerUI(c =>
            {
                //啟用中間件服務對swagger-ui，指定Swagger JSON終結點
                c.SwaggerEndpoint($"/swagger/{VERSION}/swagger.json", PROJECTNAME);
            });
            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

namespace ZQSwaggerDemo
{
    /// <summary>
    /// Swagger調試header
    /// </summary>
    public class SwaggerHttpHeaderOperation : IOperationFilter
    {
        /// <summary>
        /// 
        /// </summary>
        /// <param name="operation"></param>
        /// <param name="context"></param>
        public void Apply(OpenApiOperation operation, OperationFilterContext context)
        {
            operation.Parameters.Add(new OpenApiParameter()
            {
                Name = "Token",
                In = ParameterLocation.Header,
                Required = false,
                Schema = new OpenApiSchema { Type = "string" }
            });
        }
    }
}

6、啟動項目，訪問：http://localhost:45039/swagger/index.html 可以看到之前寫的注釋都在文檔中體現了出來

7、調試接口，對想要調試的接口，展開接口后，點擊Try it out按鈕，這里我們可以看到之前擴展的Header部分參數（本DEMO僅示范，并未使用，實際項目中還是經常需要自定義一些header參數），填寫好參數后，點擊Execute調用接口，可以看到成功返回了數據。

歡迎大家交流評論，共同進步，有任何建議或問題隨時私聊我

如果本文對您有幫助，請關注，點贊，這是對我繼續分享技術最好的鼓勵。

有需要本文DEMO的，私聊關鍵字：SwaggerDEMO