前言
.Net Core中有两个集成NSwag的包,分别为Swashbuckle和NSwag。两者的配置大同小异。这里以NSwag为例。
一、前期准备
1、初始化asp.net core 测试项目
新建asp.net core项目,此处略过;
新建apicontroller,并编写测试代码;
[Route("api/[controller]")] [ApiController] public class UserApiController : ControllerBase { /// <summary> /// 获取用户信息,根据用户id /// </summary> /// <param name="id">用户id</param> /// <returns></returns> [HttpGet("getuser/{id}")] public ActionResult GetUser(int id) { User u = new User { Id=1,Name="Jack"}; return Ok(new { ok = true, data = u }); } /// <summary> /// 添加用户 /// </summary> /// <param name="user">用户信息</param> /// <returns></returns> [HttpPost("postuser")] public ActionResult AddUser([FromBody]User user) { return Ok(new { ok = true, data = user }); } }
public class User { /// <summary> /// 用户id /// </summary> public int Id { get; set; } /// <summary> /// 用户姓名 /// </summary> public string Name { get; set; } }
2、使用nuget安装 NSwag.AspNetCore
方式一:通过vs图形界面安装;
方式二:通过nuget 命令安装:
Install-Package NSwag.AspNetCore
二、配置Swagger
1、添加并配置 Swagger 中间件
在应用的Startup类中的ConfigureServices 方法中,注册所需的 Swagger 服务:
public void ConfigureServices(IServiceCollection services) { services.AddControllersWithViews(); // Register the Swagger services services.AddSwaggerDocument() }
在 Startup类中的Configure 方法中,启用中间件为生成的 Swagger 规范和 Swagger UI 提供服务:
public void Configure(IApplicationBuilder app) { app.UseStaticFiles(); // Register the Swagger generator and the Swagger UI middlewares app.UseOpenApi(); app.UseSwaggerUi3(); app.UseMvc(); }
启动应用。 转到:
http://localhost:/swagger,以查看 Swagger UI。
http://localhost:/swagger/v1/swagger.json,以查看 Swagger 规范。
2、自定义 API 文档
API 信息和说明
在 Startup.ConfigureServices 方法中,传递给 AddSwaggerDocument 方法的配置操作会添加诸如作者、许可证和说明的信息:
public void ConfigureServices(IServiceCollection services) { //services.AddControllers(); services.AddControllersWithViews(); services.AddSwaggerDocument(config => { config.PostProcess = document => { document.Info.Version = "v1"; document.Info.Title = "UserManageApp API"; document.Info.Description = "A simple ASP.NET Core web API"; document.Info.TermsOfService = "None"; document.Info.Contact = new NSwag.OpenApiContact { Name = "张三", Email = string.Empty, Url = "https://example.com" }; document.Info.License = new NSwag.OpenApiLicense { Name = "Use under LICX", Url = "https://example.com/license" }; }; }); }
Swagger UI 显示版本的信息:
XML 注释
若要启用 XML 注释,请执行以下步骤:
以windows先使用vs为例:
三、参考
https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-nswag?view=aspnetcore-3.0&tabs=visual-studio
*以上讲解知识入门级的,能大体使用起来,能满足一般性需求;
总结
以上就是这篇文章的全部内容了,希望本文的内容对大家的学习或者工作具有一定的参考学习价值,谢谢大家对站长技术的支持。
本文介绍一下ASP.Net中对XML的用法,这里飞刀我只是展现了XML与DataSet相结合的...
近日在腾讯云AI大数据新品发布会上腾讯云副总裁王龙向听众全面介绍了当前腾讯云...
在.NET Core的项目中,如果我们要在项目中引用其它DLL文件,不建议直接在项目引...
Asahi Linux 项目已公布了第一份进度报告,详细介绍了其为了将 Linux 移植到 App...
下面看下正则表达式实现手机号中间4位数隐藏或者只显示末尾四位数 // 匹配手机号...
vscode简介 什么是vscode 简单来说,vscode是一款 文本编辑器,而不是ide 。这就是...
我将利用三天的时间来完成制作京东首页的静态页面效果,其中包含的内容有html以...
不过首先你会发现,你在不同的地区或者不同的网络(电信、联通、移动)的情况下...
我们在做项目的时候经常要将数据库的数据导出到excel中,很多asp用户并不知道怎...
有时候commit后发现注释不太合适需要修改,网上查找了一些方法,经测试后整理一...