asp.net.core学习笔记1：swagger的使用和webapi接收Jobject对象

　　环境：asp.net.core 3.1 （一觉醒来官方已经不推荐3.0了，于是没有任何core经验，也只能开始了3.1的开发学习）

　　由于现有项目前后端分离、微服务化日趋流行，所以上手不采用web应用（razor页面，mvc），直接使用webapi，也许后续的项目会采用SignalR做实时数据。回归正题，使用webapi常用的辅助工具swagger必须有姓名，好处就不说了，谁用谁知道。

　　一、swagger的使用。网上相关教程（包括汉化等）较多，只简述基本步骤，提供一些小技巧应用。

       1.在nuget管理器中添加Swashbuckle.AspNetCore包引用；

　　2.添加service配置。在startup.cs中在ConfigureServices方法中添加swagger的服务配置代码。注意配置xml的路径和名称，需要在项目属性“生成”中配置名称和地址。

 services.AddSwaggerGen(c=> {
                c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "My API", Version = "v1" });
                c.IncludeXmlComments(System.IO.Path.Combine(System.AppContext.BaseDirectory, "API.xml"));
            });

 

 　　3.添加swagger配置。在startup.cs中Configure中添加代码配置应用程序。swagger的endpoint常规配置即可。

小技巧：将swagger的路由前缀置为空，并将调试的启动路径设置为index.html。由于是前后端分离，后端服务中不提供界面，设置为index.html为启动路径，可以在调试的第一时间打开swagger界面。

　　　　　　  app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
                c.RoutePrefix = "";
            });

 

　　二、Webapi接收jobject对象。json在api中的使用非常常见，但是core在api的请求中是不支持弱类型对象的，可以确定的是支持自定义类型和基础数据类型。通常使用post发送一个json，如果json是api已经定义好的强类型，那么core可以将json直接反序列化成自定义类型。但如果json的内容不固定，或不便于定义强类型，我们通常选择是弱类型jobject，但是很遗憾的是3.0之前是不支持json反序列化jobject的。（3.0之前的core通常自定义一个模型绑定构建器和模型绑定方法，参考资料3）

       3.0之后添加了对jobject的优化支持，引用包 Microsoft.AspNetCore.Mvc.Newtonsoft，并在配置服务的时候对controller添加json的支持即可，如下：

　　services.AddControllers().AddNewtonsoftJson();

　　然后便可以在controll中添加post的api。

 

 

 

 

 

 有兴趣的同志可以研究参考资料3，看看core1.1是如何实现模型绑定的（实践过程中有瑕疵，不建议采用这种古早的方法）。

 

参考资料：

1.https://lbadri.wordpress.com/2014/11/23/web-api-model-binding-in-asp-net-mvc-6-asp-net-5/

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

3.https://www.cnblogs.com/showmu/p/6264950.html