net core体系-API-Restful+Swagger搭建API

时间:2022-09-30 21:09:43

本篇主要简单介绍下.net core下搭建WebApi

项目结构

项目结构其实不用多说,基本上大同小异。

  • Controller:对外暴露的契约
  • Business/IBussiness:业务逻辑层实现及接口
  • DataAccess:数据访问层
  • Model:实体类库
  • Common:公共方法类库

net core体系-API-Restful+Swagger搭建API

Swagger

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码,了解更多内容,见参考资料。

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

官网:http://swagger.io/

Swagger集成

首先通过NuGet加载依赖包Swashbuckle.AspNetCore

net core体系-API-Restful+Swagger搭建API

然后右击你的项目,在属性中,勾选下生成XML文档文件,Swagger会自动解析对应的XML进行匹配。

net core体系-API-Restful+Swagger搭建API

然后开始编码部分,在Startup.csConfigureServicesf方法下加入下面的代码:

services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" }); var basePath = PlatformServices.Default.Application.ApplicationBasePath; var xmlPath = Path.Combine(basePath, "MyDemo.xml"); var xmlPath1 = Path.Combine(basePath, "MyDemo.Model.xml"); c.IncludeXmlComments(xmlPath);
c.IncludeXmlComments(xmlPath1);
});

这里我将Model层的Xml也加载了,这样在api文档上也能显示对应字段的描述。

Configure 方法中加入下面代码:

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

配置到这里,可以直接运行看下效果了,结果运行后发现报错如下:

net core体系-API-Restful+Swagger搭建API

那是因为主项目没有引用Model这个类库,导致在主项目的debug中没有生产对应的xml,引用下,重新生产再次运行,输入/swagger就能看到对应的效果了。

记得项目接入的时候才1.0.0的版本,如今2.3.0的版本样式也变了很多了。

net core体系-API-Restful+Swagger搭建API

这样我可以启动默认页设为/swagger,右击docker-compose修改对应的url:

net core体系-API-Restful+Swagger搭建API

代码编写

逻辑代码不多说,基本没什么区别,大多数常用的属性和方法.net core基本都支持,放心大胆的写吧。

这里推荐使用异步编程await,async,但要注意的是,一定要异步到底,避免阻塞。

可以简单看个例子:

//Dal层:
public static async Task<ResponseResult> Delete(long id)
{
var result = new ResponseResult();
try
{
using (var conn = DatabaseManager.GetConnection(DatabaseManager.DBName))
{
await conn.OpenAsync();
string sql = $@"DELETE FROM USER WHERE Id=@Id";
await conn.ExecuteAsync(sql, new { Id = id, UpdateTime = DateTime.Now });
}
}
catch (Exception ex)
{
//记录日志
return new ResponseResult { Result = false, Code = ResponseCode.UnknownException, ErrorMessage = ex.Message };
}
return result;
}
//BLL层
public static async Task<ResponseResult> Delete(long id)
{
if (id <= 0)
return new ResponseResult { Result = false, ErrorMessage = "未传入主键或主键非法", Code = ResponseCode.NeedsKeyParameter };
return await UserDataAccess.Delete(id);
}
//Controller
[HttpDelete("{id}")]
public async Task<IActionResult> Delete(long id)
{
return AssertNotFound(await UserService.Delete(id));
}

由于是演示,这里用的静态类和静态方法,也省去了Interface,实际项目中可以根据需要选择最合适的。

总结

.net core开发web api还是比较方便的,大家可以试试。

其他资源:

https://blog.csdn.net/boonya/article/details/80321229

https://blog.csdn.net/xiaouncle/article/details/83995809

https://blog.csdn.net/sinat_16998945/article/details/84307028