Asp.Net Core使用swagger生成api文档的完整步骤_实用技巧

来源:脚本之家  责任编辑:小易  

asp.net mvc5只能运行在Windows,一般通过IIS发布;asp.net core开源,可跨平台,能够发布到Linux等系统上。asp.net core做了很多的整合工作,目前来说完成了最基本的一部分类库的迁移。从前景上来说,asp.net core肯定是以后的一种潮流,随着docker等技术的普及,跨平台的重要性凸显,必须要使用asp.net core编写的接口才能发布到linux中,也就是asp.net core编写的接口可以做成docker的镜像发布,而asp.net mvc5不能。所以最终肯定是会慢慢都转移到asp.net core上来。但是这需要一个比较久的过程。因为从asp.net mvc5转移到asp.net core需要一定时间的学习,即使在国外也需要一定过程。而国内由于语言环境、开发工具(需要VS2015才能进行asp.net core的开发)等的原因,肯定需要更久。国内的技术一直以来也比较保守。如果单纯的以在国内找个开发的工作的话,建议先熟悉下asp.net mvc5。如果确实有跨平台的需求,或者团队成员都对新技术有很高的热情,从事的也是全新的项目的话,就使用asp.net core吧www.zgxue.com防采集请勿采集本网。

前言

.Net Core中有两个集成NSwag的包,分别为Swashbuckle和NSwag。两者的配置大同小异。这里以NSwag为例。

不一样 ASP.NET Core 是一个用于net程序跨平台的框架,在它的基础上会重写.NET Framework(windows)、Mono(Linux),以实现所有net程序、网站的跨平台 ASP.net 是一种e68a84e799bee5baa6e79fa5e

一、前期准备

在asp.net core 里非常建议使用entity framework,因为新的entity framework core定义了一套接口标准,就如同ado.net一样,只要有厂家实现了这套接口就行,而且厂家的实现肯定会更好一些。在asp.

1、初始化asp.net core 测试项目

1、CORS的原理:CORS定义百一种跨域访问的机度制,可以让AJAX实现跨域访问。CORS 允许问一个答域上的网络应用向另一个域提交跨域 AJAX 请求。实现此功能非常简版单,只需由服务器发送一个权响应

新建asp.net core项目,此处略过;

它在Windows,MacOS和Linux上提供构建和运行命令行应用程序的工具,它也是用于构建ASP.Net Core Web应用程序的工具。在Windows Server Nano上运行.Net Core,使用熟悉的工具在Windows容器中构建和运行微

新建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为例: 在“解决方案资源管理器”中右键单击该项目,然后选择“编辑 .csproj” 。 手动将突出显示的行添加到 .csproj 文件 :

三、参考

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

*以上讲解知识入门级的,能大体使用起来,能满足一般性需求;

总结

以上就是这篇文章的全部内容了,希望本文的内容对大家的学习或者工作具有一定的参考学习价值,谢谢大家对真格学网的支持。

这个吧,可能有些东西你不太理解造成的。关于性能提升的问题,net core是否性能提升10倍?答案是还真差不多!为什么呢?这是因为.net core为了跨平台,编译的方式使用的是dotnet publish-r 版本,例如发布到windows X64的机器上,使用的命令就应该是dotnet publish-r win-x64这样的命令进行发布。而运行方式呢,使用的是dotnet run xx.dll,或者直接dotnet xx.dll,它并不依赖于IIS!当然可以在IIS上部署,也就是在配置文件中使用dotnet 其中参数为xx.dll效果是一样的—但是一旦这样部署的样,受制于IIS(多数情况下使用的是IIS10.0),尤其多线程测试时weblimit参数不做更新的话,性能上有影响,即使数据很大也是有影响的。当然如果你直接使用IIS把源码丢过去,在配置文件中使用允许编译的方式的话,这种方式其实与.net framework的效果是一样的,并没有任何性能上的优势—这种情况只是你把net core看作是net framework的一个版本一样,他自然和其他版本相关不大!所以你不说话你的测试方式自然性能上无法估量。net core相比之下的优势其实除了性能上的提高就是跨平台(其实是源码跨平台),什么意思呢?net framework的移植性非常好,生成一个通用的dll(MSIL中间文件),然后该文件由不同机器上的运行环境自行翻译(JIT功能),一般认为是边翻译边执行,当然为了整体的性能问题,JIT首次编译的内容(调用的片段才会被翻译,不调用的不会翻译)存储到Native上,下次再调用时不用翻译过的代码时,JIT会跳过翻译,直接使用使用首次翻译过的片段。所以在以前的时候,有时我们为了性能,玩Native文件,而netcore后边指定版本的作用,其实就是翻译成可执行的二进制PE文件,当然他需要指定操作系统的,比如ubuntu等linux发行版上都可以的!想来看看,netcore本身在net framework上进行了重写,生成的也是针对不同系统的可执行内容,所以性能上肯定有所提升是绝对的。当然,这种方式最适合的方式还是容器方式(docker),所以性能上要比在IIS上提升不少—当然不能是类似.net framework直接源码的形式,有点类似于.net framework,但是比framework发布的形式还要高些,而性能提升也是基本这两种形式的对比!当然,严格来说.net core也是试水跨平台的方式,他去掉了.net framework的大多数内容,所以主要的体现就以下三点:1,跨平台2,重写库,性能上的提高3,为docker做足准备(也是跨平台的扩展之一)换句话来说,如果你不是基于以上几种的考虑,那么为什么要选择net core呢?要知道每种技术都有他适应的场景的,如果你是winform/WPF时,没有考虑net core的必要性,而且net core也不支持!如果是Azercloud的话,net core小巧,且服务专一,当然可以考虑net core.如果你公司考虑到使用linux发行版以避免高昂的windows费用,还有一堆.net程序员的话,net core肯定是你的选择优势—net framework不支持linux系统啊!所以我认为技术只是适用!也不是用来比较,net framework与net core的定位是相当明显且不相互冲突,所以只是一种选择罢了,而不是谁一定比谁牛B!内容来自www.zgxue.com请勿采集。


  • 本文相关:
  • asp.net core webapi 使用swagger生成帮助页实例
  • .net core2.1 webapi新增swagger插件详解
  • .net core利用swagger进行api接口文档管理的方法详解
  • asp.net core webapi使用swagger时api隐藏和分组详解
  • .net mvc中viewdata,viewbag和tempdata的区别浅析
  • gridview中动态设置commandfield是否可用或可见的小例子
  • .net jmail邮件发送(含抄送、密送、多发、日志记录)实例代码
  • asp.net连接数据库读取数据示例分享
  • asp.net mvc scheduler的实现方法详解
  • asp.net mvc自定义pager封装与优化
  • 详解asp.net七大身份验证方式以及解决方案
  • asp.net gridview里添加汇总行
  • asp.net 2.0,c#----图像特效处理
  • .net自带的库生成zip文件的方法
  • asp.net core mvc 是不是未包含使用UA 动态选择displayModel
  • 请问:ASP.net mvc5和asp.net.core有什么区别呢?在今后的发展中这个前景怎么样?
  • 请问asp.net core mvc怎么使用ef连接现有数据库?
  • 如何在ASP NET Core中实现CORS跨域
  • ASP.net core是什么,和ASP.net一样吗?
  • asp.net core里面,EF和NH哪个对Oracle的支持更好?
  • 如何在ASP NET Core中实现CORS跨域
  • Net 框架和.Net Core,我该用哪个?怎么选
  • asp.net core 上传文件服务器拒绝是为什么?
  • ASP.NET Core win2003上可以用吗
  • 网站首页网页制作脚本下载服务器操作系统网站运营平面设计媒体动画电脑基础硬件教程网络安全基础应用实用技巧自学过程首页asp.net实用技巧asp.net core webapi 使用swagger生成帮助页实例.net core2.1 webapi新增swagger插件详解.net core利用swagger进行api接口文档管理的方法详解asp.net core webapi使用swagger时api隐藏和分组详解.net mvc中viewdata,viewbag和tempdata的区别浅析gridview中动态设置commandfield是否可用或可见的小例子.net jmail邮件发送(含抄送、密送、多发、日志记录)实例代码asp.net连接数据库读取数据示例分享asp.net mvc scheduler的实现方法详解asp.net mvc自定义pager封装与优化详解asp.net七大身份验证方式以及解决方案asp.net gridview里添加汇总行asp.net 2.0,c#----图像特效处理.net自带的库生成zip文件的方法java正则表达式 pattern和matche未将对象引用设置到对象的实例 (asp.net(c#)网页跳转七种方法小结未能加载文件或程序集“xxx”或它asp.net“服务器应用程序不可用”asp.net中的几种弹出框提示基本实asp.net gridview 72般绝技asp.net生成excel并导出下载五种asp.net汉字转拼音和获取汉字首字asp.net对路径"xxxxx"asp.net updatepanel的简单用法如何为asp.net core添加protobuf支持详解asp.net mvc5网站开发之用户资料的修改和asp.net开发者使用jquery应该了解的几件事asp.net ajax 4.0的模版编程(template prasp.net 临时数据保存实现代码asp.net中datatable与dataset之间的转换示vs2010新建站点发布并访问步骤详解javascript调用webservice的多种方法利用noesis.javascript开源组件.net中执行
    免责声明 - 关于我们 - 联系我们 - 广告联系 - 友情链接 - 帮助中心 - 频道导航
    Copyright © 2017 www.zgxue.com All Rights Reserved