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