asp.net core 一个中小型项目实战的起手式——Swagger配置
交流群:863563315
一、Swagger是什么
Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。
二、如何在项目中加入Swagger
- Swagger安装引用
右键Web项目依赖项>管理NuGet程序包>在搜索框输入"Swashbuckle.AspNetCore",然后单击安装
- 添加并配置Swagger中间件
首先在Startup类中引入Swagger:
using Swashbuckle.AspNetCore.Swagger;
将 Swagger 生成器添加到ConfigureServices 方法中的服务集合中:
//注册Swagger生成器,定义一个和多个Swagger文档 services.AddSwaggerGen(p => { p.SwaggerDoc("v1", new Info {Title = "数据管理器API文档", Version = "V1"}); });
在Configure方法中,启用中间件为生成的JSON文档和SwaggerUI提供服务:
//启用中间件服务生成Swagger作为JSON终结点 app.UseSwagger(); //启用中间件服务对swagger-ui,指定Swagger JSON终结点 app.UseSwaggerUI(p => { p.SwaggerEndpoint("/swagger/v1/swagger.json", "数据管理器API文档 v1"); });
启动应用,并跳转到 http://localhost:<port>/swagger/v1/swagger.json 生成的描述终结点的文档显示如下json格式。
可在 /swagger 找到 Swagger UI。 通过 Swagger UI 浏览 API文档,如下所示。
- 为接口方法提供注释
首先右键【解决方案资源管理器】中的项目,然后选【属性】
查看“生成”选项卡的【输出】部分下的【XML 文档文件】框
启用 XML 注释后会为未记录的公共类型和成员提供调试信息。如果出现很多警告信息 例如,以下消息指示违反警告代码 1591。可以在进制显示警告中加入警告代码,这样不会再在错误列表中显示1591类型的警告了。
在Swagger注册服务中增加:
//注册Swagger生成器,定义一个和多个Swagger文档 services.AddSwaggerGen(p => { p.SwaggerDoc("v1", new Info {Title = "数据管理器API文档", Version = "V1"}); // 为 Swagger JSON and UI设置xml文档注释路径 var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在绝对目录 var xmlPath = Path.Combine(basePath, "DataManager.Web.xml");//此处的文件名要对应到项目属性中生成的xml文件名 p.IncludeXmlComments(xmlPath); });
在控制器目录下新增一个WebApi测试控制器,测试下效果
[Route("api/[controller]/[action]")] [ApiController] public class SwaggerTestController : ControllerBase { /// <summary> /// 这是一个Swagger测试接口 /// </summary> /// <returns></returns> [HttpGet] public IActionResult Test() { return new JsonResult(new {key = "Name", value = "test"}); } }
访问/swagger:
好了,今天的在ASP.NET Core WebApi使用Swagger生成api说明文档的教程就到这里了。希望能够对大家学习在ASP.NET Core中使用Swagger生成api文档有所帮助!
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· 浏览器原生「磁吸」效果!Anchor Positioning 锚点定位神器解析
· 没有源码,如何修改代码逻辑?
· 一个奇形怪状的面试题:Bean中的CHM要不要加volatile?
· [.NET]调用本地 Deepseek 模型
· 一个费力不讨好的项目,让我损失了近一半的绩效!
· 微软正式发布.NET 10 Preview 1:开启下一代开发框架新篇章
· 没有源码,如何修改代码逻辑?
· PowerShell开发游戏 · 打蜜蜂
· 在鹅厂做java开发是什么体验
· WPF到Web的无缝过渡:英雄联盟客户端的OpenSilver迁移实战