Core + Vue 后台管理基础框架8——Swagger文档
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文档，要舒服、省事儿得多？