Core + Vue 後臺管理基礎框架8——Swagger文檔

一、前言

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

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

二、實現

　　（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文檔直接掛在系統跟路徑上。

三、效果
啓動後端訪問http://localhost:5000，以下：

 

 

 

 

　　咱們以獲取用戶我的信息爲例，走swagger調用下：

 

 　　由於沒有token嘛，天然就401了。好，那咱們走登陸接口，取一個合法token（登陸是不須要認證的，因此能夠直接走swagger調用）：

 

 

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

 

 

 

 

 

 　　提供了JWT，如今咱們再從swagger調用獲取我的信息接口：

 

 　　能夠看到，已經成功調用接口了。既然前言部分咱們說到了接口自描述，那咱們就來看看，文檔是否作到了自描述。

 

　　如上， rest終結點有了，接口地址有了，接口描述也有了。此方法沒有入參，因此看不到入參，那咱們看出參或者返回結果，是同樣的：

 

 　　結果信息描述，也有了。是否是比手擼接口文檔，或者MD文檔，要舒服、省事兒得多？