基于.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();
    });
}

运行后的接口清单

 

运行后的请求结果

 

 

---

参考资料：

1.https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-3.0&tabs=visual-studio

2.https://www.cnblogs.com/laozhang-is-phi/p/11520048.html

3.https://q.cnblogs.com/q/120085/

4.https://blog.csdn.net/qq_25086397/article/details/103682863