夸克之书

  • 首页
  • 科普
  • 笔记
  • .NET/C#
  • 物联网
  • 算法
  • Linux
  • 树莓派
夸克之内,别有洞天
  1. 首页
  2. .NET/C#
  3. 正文

ASP.NET Core 3.1 WebApi Swagger与API版本控制的美妙结合

2019-12-16 6315点热度 1人点赞 1条评论

在编写API时,很多时候会用到API版本控制和API文档编写及测试调试。本文主要记录如何使用Microsoft.AspNetCore.Mvc.Versioning进行API版本控制以及Swagger API书写框架的使用。

一、JSON 配置

从asp.net core 3.0开始,默认使用微软新的 JSON组件(System.Text.Json),尽管据微软实验室测试性能高于Newtonsoft.Json ,但是推荐还是用 Newtonsoft.Json,比较成熟而且对很多比较特殊的情况都有处理,使用方式如下:

1、引用 nuget 包 Microsoft.AspNetCore.Mvc.NewtonsoftJson
2、配置使用 Newtonsoft.Json

services.AddControllers()
    .AddNewtonsoftJson(options =>
    {
        options.SerializerSettings.ContractResolver = new DefaultContractResolver();
    });

当然,对于是使用System.Text.Json还是Newtonsoft.Json全凭个人喜好和项目需求。

二、Api版本控制

在编写RESTFUL API时可能时常会进行更新和修改,但如果遇到API是开放给其它系统使用的情况时,我们不可能在启用下个版本时将上一个版本的去掉。因此就需要引入API的版本控制,操作时根据不同的版本去请求即可。

1、使用Nuget安装Api版本控制库

.NET Core Mvc中,微软官方提供了一个可用的Api版本控制库Microsoft.AspNetCore.Mvc.Versioning。 这里我们可以使用Nuget安装这个包。

2、修改Startup类

Microsoft.AspNetCore.Mvc.Versioning库安装完成之后,下一步我们来添加Api版本控制服务。这里我们需要在Startup类的ConfigureService方法中添加以下代码。

services.AddApiVersioning(o => {
    o.ReportApiVersions = true;
    o.AssumeDefaultVersionWhenUnspecified = true;
    o.DefaultApiVersion = new ApiVersion(1, 0);
});

3、创建多版本Api

我们在项目的Controller文件夹下面创建两个文件夹,分别是v1和v2。对应v1和v2两个版本。

当文件夹创建好之后,在v1和v2文件夹下面均创建一个UserController的RESTful API控制器。

%title插图%num

创建好后此时项目结构如下:

%title插图%num

然后修改v1和v2版本的Attribute,将v1下面的UserController Attribute替换为:

[ApiVersion("1")]
[Route("v{version:apiVersion}/[controller]")]
[ApiController]

将v2下面的UserController Attribute替换为:

[ApiVersion("2")]
[Route("v{version:apiVersion}/[controller]")]
[ApiController]

请注意:不同版本的Controller不同之处仅为ApiVersion中的值不同。

此时你的Control应该是这样的↓↓↓↓

[ApiVersion("2")]
[Route("v{version:apiVersion}/[controller]")]
[ApiController]
public class UserController : ControllerBase
{
    //....
}

然后分别修改Controller下的GET方法,让我们可以在浏览器中直接看到结果。修改获取单个信息的方法为:

[HttpGet("{id}", Name = "Get")]
public string Get(int id)
{
    return "this is v1 api";  //V2:this is v2 api
}

4、运行测试

F5运行项目,然后在浏览器中输入对应版本的API URL即可通过既定的版本请求不同版本的API。

%title插图%num
v1版本的API
%title插图%num
v2版本的API

此时你已经完成了最简单的API版本控制方法,接下来是使用swagger来描述我们不同版本的API。

三、使用Swagger

1、安装依赖

首先我们还是通过Nuget安装Swashbuckle.AspNetCore。

注意:当前支持ASP.NET Core3.1的Swagger还是预览版,在安装之前请勾选“包括预览版项目”,并安装最新的预览版。截止本篇文章,最新预览版为Swashbuckle.AspNetCore 5.0.0-rc5(2019年12月16日)(已经更新正式版)

2、生成项目XML

右键项目,选择“属性”,切换到生成选项卡,勾选“XML文档文件”。 Swagger将根据生成的XML构建API文档。

%title插图%num

3、Swagger服务注册

在ConfigureServices方法中注册以下服务:

services.AddSwaggerGen(option =>
{
    //分别注册v1和v2
    option.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "WithsaltWebApiDemo API",
        Description = "API for WithsaltWebApiDemo",
        Contact = new OpenApiContact() { Name = "withsalt", Email = "withsalt@geeiot.net" }
    });
    option.SwaggerDoc("v2", new OpenApiInfo
    {
        Version = "v2",
        Title = "WithsaltWebApiDemo API",
        Description = "API for WithsaltWebApiDemo",
        Contact = new OpenApiContact() { Name = "withsalt", Email = "withsalt@geeiot.net" }
    });

    option.DocInclusionPredicate((docName, apiDesc) =>
    {
        var versions = apiDesc.CustomAttributes()
            .OfType<ApiVersionAttribute>()
            .SelectMany(attr => attr.Versions);

        return versions.Any(v => $"v{v.ToString()}" == docName);
    });

    option.OperationFilter<RemoveVersionParameterOperationFilter>();
    option.DocumentFilter<SetVersionInPathDocumentFilter>();

    //项目xml文档
    //注意:这里包含了一个Demo.Model.xml,是因为我要显示实体类。
    option.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $"{typeof(Startup).Assembly.GetName().Name}.xml"), true);
    option.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $"Demo.Model.xml"), true);
});

其中包含了两个自定义的 OperationFilter :

public class SetVersionInPathDocumentFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        var updatedPaths = new OpenApiPaths();

        foreach (var entry in swaggerDoc.Paths)
        {
            updatedPaths.Add(
                entry.Key.Replace("v{version}", swaggerDoc.Info.Version),
                entry.Value);
        }

        swaggerDoc.Paths = updatedPaths;
    }
}

public class RemoveVersionParameterOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // Remove version parameter from all Operations
        var versionParameter = operation.Parameters.Single(p => p.Name == "version");
        operation.Parameters.Remove(versionParameter);
    }
}

配置中间件。在Configure中添加以下代码:

//Enable middleware to serve generated Swagger as a JSON endpoint.
app.UseSwagger();
//Enable middleware to serve swagger-ui (HTML, JS, CSS etc.), specifying the Swagger JSON endpoint
app.UseSwaggerUI(option =>
{
    option.SwaggerEndpoint("/swagger/v2/swagger.json", "V2 Docs");
    option.SwaggerEndpoint("/swagger/v1/swagger.json", "V1 Docs");

    option.RoutePrefix = string.Empty;
    option.DocumentTitle = "WithsaltWebApiDemo API";
});

4、运行测试

配置到这里,可以直接运行看下效果了。

%title插图%num

可以在属性,调试选项卡中修改默认的启动页为Swagger Api页面。将启动浏览器参数设置为Swagger默认页面即可。ASP.NET Core WebApi中默认为空。

也可以点击Try it out来进行接口的测试!

Demo

本文Demo下载:点此下载

参考

1、.Net Core中的Api版本控制
2、asp.net core 3.0 中使用 swagger
3、SparkTodo

本作品采用 知识共享署名-非商业性使用 4.0 国际许可协议 进行许可
标签: 暂无
最后更新:2020-12-13

afirefish

这个人很懒,什么都没留下

打赏 点赞
< 上一篇
下一篇 >

文章评论

您需要 登录 之后才可以评论
放松一下
https://www.quarkbook.com/wp-content/uploads/2021/05/凤凰传奇-海底(Live).flac
分类
  • .NET/C#
  • Linux
  • 树莓派
  • 物联网
  • 科普
  • 笔记
  • 算法
  • 默认
最新 热点 随机
最新 热点 随机
维持宇宙的四种“力量”——关于四大基本力 MinGW图形安装界面里面没有mingw32 make.exe解决办法 Windows Server 2022安装Intel I225-V/I226-V驱动 System.Text.Json与Newtonsoft.Json Json序列化与反序列化性能对比 R86S散热改造 Windows移除多余输入法'Unknown Locale (qaa-Latn)'
Windows Server 2022安装Intel I225-V/I226-V驱动MinGW图形安装界面里面没有mingw32 make.exe解决办法维持宇宙的四种“力量”——关于四大基本力
严肃一点的排序算法(3) – 猴子排序 必须添加对程序集“netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51”的引用。 解决Visual Studio 2022中无法编译 .NET Framework 4.5/4.5.1项目(Visual Studio 2022安装.NET Framework 4.5) PVE重启后LVM Thin数据丢失,错误:Volume group "****" has insufficient free space (128 extents): 4048 required. Ubuntu/Debian安装Frps并设置开机启动 Windows桌面图标空白修复
最近评论
afirefish 发布于 4 个月前(11月28日) 非常感谢,非常棒!
》随缘《 发布于 4 个月前(11月20日) 最新【一键处理】方法: https://github.com/MrXhh/VSTools/rele...
管理员 发布于 9 个月前(06月22日) emmmm....服务器好一点???
wking 发布于 10 个月前(05月23日) 请问贵博客是怎么优化的,网页响应速度非常快。我博客同样的WordPress和kratos主题,但点一...
去月球 发布于 1 年前(01月17日) 如果使用CSI的摄像头应该怎么修改命令呢
书签
  • 打赏
  • 毒鸡汤
  • 米店
  • 金鱼直播间

COPYRIGHT © 2022 quarkbook.com. ALL RIGHTS RESERVED.

Theme Kratos Made By Seaton Jiang

蜀ICP备15036129号-9

登录
注册|忘记密码?