Asp.Net Core使用swagger生成api文档的完整步骤
脚本之家 / 编程助手:解决程序员“几乎”所有问题!
脚本之家官方知识库 → 点击立即使用
前言
.Net Core中有两个集成NSwag的包,分别为Swashbuckle和NSwag。两者的配置大同小异。这里以NSwag为例。
一、前期准备
1、初始化asp.net core 测试项目
新建asp.net core项目,此处略过;
新建apicontroller,并编写测试代码;
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | [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 }); } } |
1 2 3 4 5 6 7 8 9 10 11 | public class User { /// <summary> /// 用户id /// </summary> public int Id { get ; set ; } /// <summary> /// 用户姓名 /// </summary> public string Name { get ; set ; } } |
2、使用nuget安装 NSwag.AspNetCore
方式一:通过vs图形界面安装;
方式二:通过nuget 命令安装:
二、配置Swagger
1、添加并配置 Swagger 中间件
在应用的Startup类中的ConfigureServices 方法中,注册所需的 Swagger 服务:
1 2 3 4 5 6 7 | public void ConfigureServices(IServiceCollection services) { services.AddControllersWithViews(); // Register the Swagger services services.AddSwaggerDocument() } |
在 Startup类中的Configure 方法中,启用中间件为生成的 Swagger 规范和 Swagger UI 提供服务:
1 2 3 4 5 6 7 8 9 10 | 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 方法的配置操作会添加诸如作者、许可证和说明的信息:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | 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为例:
- 在“解决方案资源管理器”中右键单击该项目,然后选择“编辑 .csproj” 。
- 手动将突出显示的行添加到 .csproj 文件 :
三、参考
https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-nswag?view=aspnetcore-3.0&tabs=visual-studio
*以上讲解知识入门级的,能大体使用起来,能满足一般性需求;
总结
以上就是这篇文章的全部内容了,希望本文的内容对大家的学习或者工作具有一定的参考学习价值,谢谢大家对脚本之家的支持。
微信公众号搜索 “ 脚本之家 ” ,选择关注
程序猿的那些事、送书等活动等着你
本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。
如若内容造成侵权/违法违规/事实不符,请将相关资料发送至 reterry123@163.com 进行投诉反馈,一经查实,立即处理!
相关文章
扩展 Entity Framework支持复杂的过滤条件(多个关键字模糊匹配)
之前遇到一个棘手的Linq to EF查询的技术问题,现有产品表Product,需要根据多个关键字模糊匹配产品名称, 现将解决方案分享出来,按兴趣的朋友可以参考下2012-12-12浅谈从ASP.NET Core2.2到3.0你可能会遇到这些问题
这篇文章主要介绍了ASP.NET Core2.2到3.0可能会遇到的问题,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧2019-04-04asp.net MVC 在Controller控制器中实现验证码输出功能
这篇文章主要介绍了asp.net MVC 在Controller控制器中实现验证码输出功能,本文给大家介绍非常详细,具有一定的参考借鉴价值,需要的朋友可以参考下2019-12-12Asp.net response对象与request对象使用介绍
这篇文章主要介绍了Asp.net response对象与request对象使用,需要的朋友可以参考下2014-04-04asp.net String.IsNullOrEmpty 方法
2009-04-04
最新评论