基于.NET Core 3.1的WebApi集成swagger
===============================================
2020/1/8_第1次修改 ccb_warlock
===============================================
swagger作为Asp .Net的接口文档已经应用于当前系统一段时间了,比起开个postman填参数请求来说这个后台开发可以直接用swagger来快速测试接口的业务,前端开发通过查看swagger可以快速了解后台API的输入输出(毕竟开发进度紧张的情况下不可能来得及及时维护文档,但是开发环境的swagger只要代码更新就会一起更新)
最近为了试验EF Core 2.2的datetime类型存在的一个缺陷,公司也没有1个.net core 3.0以上的项目,没办法只有先改造.net core 2.2的项目到.net core 3.1以后,再进行下一步测试。
在做框架升级的时候,不得不实现swagger升级的问题。而swagger的升级问题花了点时间来处理,所以记录下过程方便以后查看。
现在的稳定版还不支持.net core 3.0+,所以Nuget里需要升级下面2个项目到5.0.0以上的预览版才能实现swagger的升级。
Swashbuckle.AspNetCore(勾选上预发行,当前要v5.0.0-rc5以上版本)
Swashbuckle.AspNetCore.Filters(勾选上预发行,当前要v5.0.0-rc9以上版本)
由于当前系统的框架用了很多注入,为了简化描述我还是拆出来记录代码片段。
1)在Startup.cs中,通过ConfigureServices初始化swagger
public IServiceProvider ConfigureServices(IServiceCollection services) { var title = "myApi"; var version = "v1"; services.AddControllers(); services.AddSwaggerGen(c => { // swagger文档配置 c.SwaggerDoc(version, new OpenApiInfo { Version = version, Title = title, //Description = $"{title} HTTP API " + v, //Contact = new OpenApiContact { Name = "Contact", Email = "xx@xxx.xx", Url = new Uri("https://www.cnblogs.com/straycats/") }, //License = new OpenApiLicense { Name = "License", Url = new Uri("https://www.cnblogs.com/straycats/") } }); // 接口排序 c.OrderActionsBy(o => o.RelativePath); // 配置xml文档 var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); c.IncludeXmlComments(xmlPath); c.OperationFilter<AddResponseHeadersFilter>(); c.OperationFilter<AppendAuthorizeToSummaryOperationFilter>(); // 安全校验 c.OperationFilter<SecurityRequirementsOperationFilter>(); // 开启oauth2安全描述 c.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme { Description = "JWT授权(数据将在请求头中进行传输) 直接在下框中输入Bearer {token}(注意两者之间是一个空格)\"", Name = "Authorization", In = ParameterLocation.Header, Type = SecuritySchemeType.ApiKey }); }); }
2)在Startup.cs中,通过Configure在管道中添加swagger
public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { var title = "myApi"; if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } else { app.UseHsts(); } //启用中间件服务生成Swagger作为JSON终结点 app.UseSwagger(); //启用中间件服务对swagger-ui,指定Swagger JSON终结点 app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", title);//注意这里的v1是根据上面的version来填的 }); app.UseRouting(); app.UseAuthorization(); app.UseEndpoints(endpoints => { endpoints.MapControllers(); }); }
运行后的接口清单
运行后的请求结果
参考资料: