Core + Vue 后台管理基礎框架8——Swagger文檔

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文檔，要舒服、省事兒得多？