1、前言

　　作為前後端分離的專案，或者說但凡涉及到對外服務的後端，一個自描述，跟程式碼實時同步的文件是極其重要的。說到這兒，想起了幾年前在XX速運，每天寫完程式碼，還要給APP團隊更新文件的慘痛經歷。給人家普及swagger，說不習慣，就要手寫的Word文件。

　　閒話少扯。一份合格的文件，最起碼要包括rest地址，HTTP方法，入參出參，入參出參的描述，如果介面包括授權，swagger文件還需要對應包括這部分的處理。做到這點，前端團隊必定會感激你的，而且一個靠譜的前端，它也一定會要求你這麼做的。再閒扯一句，我曾聽一位同事說，搞.NET的，前端後端全棧一把梭，要毛的文件。。。我仔細回想了下早幾年，好像.NETer確實全棧比較多，所謂的人少事兒多高效錢少。。。

2、實現

　　（1）新增Swashbuckle.AspNetCore包引用

　　（2）Startup工程下新增如下專案特性

 　　簡單交代下，上邊一行代表生成控制器及操作方法xml描述文件，下邊一句是說沒有描述時候，VS編譯不生成警告資訊。

　　（3）Dto工程同上

　　（4）Swagger相關服務註冊

services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo { Title = "System Management", Version = "v1" });
                
                c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
                {
                    Name = "Authorization",
                    Type = SecuritySchemeType.ApiKey,
                    Scheme = "Bearer",
                    BearerFormat = "JWT",
                    In = ParameterLocation.Header,
                    Description = "JWT Authorization header using the Bearer scheme."
                });
                c.AddSecurityRequirement(new OpenApiSecurityRequirement
                {
                    {
                        new OpenApiSecurityScheme
                        {
                            Reference = new OpenApiReference
                            {
                                Type = ReferenceType.SecurityScheme,
                                Id = "Bearer"
                            }
                        },
                        new string[] {}
                    }
                });

                c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"));
                c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "SystemManagement.Dto.xml"));
            });

c.SwaggerDoc("v1", new OpenApiInfo { Title = "System Management", Version = "v1" });這句代表文件的版本，標題等資訊；

 c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme）這部分代表告訴swagger，系統是採用bearer token認證的，方便swagger在頁面上提供
token入口，同時交代了使用JWT這種token；

 c.AddSecurityRequirement(new OpenApiSecurityRequirement）這部分則是告訴swagger全域性應用上述認證模式；

c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"));
c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "SystemManagement.Dto.xml"));
最後邊這兩句include則是告訴swagger描述文件中元資料從何而來。第（2）步中我們設定專案屬性之後，xml文件就會自動生成並輸出到系統根目錄。

（5）swagger中介軟體引入

 app.UseSwagger();

            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "System Management V1");
                c.RoutePrefix = string.Empty;
            });

c.RoutePrefix = string.Empty;這句是為了讓swagger文件直接掛在系統跟路徑上。

3、效果
啟動後端訪問http://localhost:5000，如下：

　　我們以獲取使用者個人資訊為例，走swagger呼叫下：

 　　因為沒有token嘛，自然就401了。好，那我們走登入介面，取一個合法token（登入是不需要認證的，所以可以直接走swagger呼叫）：

拿到其中的token值，然後到swagger文件頂部去認證：

 　　提供了JWT，現在我們再從swagger呼叫獲取個人資訊介面：

 　　可以看到，已經成功呼叫介面了。既然前言部分我們說到了介面自描述，那我們就來看看，文件是否做到了自描述。

　　如上， rest終結點有了，介面地址有了，介面描述也有了。此方法沒有入參，所以看不到入參，那我們看出參或者返回結果，是一樣的：

 　　結果資訊描述，也有了。是不是比手擼介面文件，或者MD文件，要舒服、省事兒得多？

&nbs