第十四节:Asp.Net Core WebApi生成在线文档-第十九节

一. 基本概念

1.背景

  使用 Web API 时,了解其各种方法对开发人员来说可能是一项挑战。 Swagger 也称为OpenAPI,解决了为 Web API 生成有用文档和帮助页的问题。 它具有诸如交互式文档、客户端 SDK生成和 API 可发现性等优点,目前有两种实现方式:

 (1).Swashbuckle.AspNetCore: 是一个开源项目,用于生成 ASP.NET Core Web API 的 Swagger 文档。(本节重点介绍)

 (2).NSwag: 是另一个用于生成 Swagger 文档并将 Swagger UI 或 ReDoc 集成到 ASP.NET Core Web API 中的开源项目。 此外,NSwag 还提供了为 API 生成 C# 和 TypeScript 客户端代码的方法。

2.什么是 Swagger/OpenAPI?

  Swagger 是一个与语言无关的规范,用于描述 REST API。 Swagger 项目已捐赠给 OpenAPI 计划,现在它被称为开放 API。 这两个名称可互换使用,但 OpenAPI 是首选。 它允许计算机和人员了解服务的功能,而无需直接访问实现(源代码、网络访问、文档)。 其中一个目标是尽量减少连接取消关联的服务所需的工作量。 另一个目标是减少准确记录服务所需的时间。

3.Swagger 规范

  Swagger 流的核心是 Swagger 规范,默认情况下是名为 swagger.json 的文档 。 它由 Swagger 工具链(或其第三方实现)根据你的服务生成。 它描述了 API 的功能以及使用 HTTP 对其进行

访问的方式。 它驱动 Swagger UI,并由工具链用来启用发现和客户端代码生成。

4.Swagger UI

  Swagger UI提供了基于 Web 的 UI,它使用生成的 Swagger 规范提供有关服务的信息。 Swashbuckle 和 NSwag 均包含 Swagger UI 的嵌入式版本,因此可使用中间件注册调用将该嵌入式版本托管在 ASP.NET Core 应用中。

二. 基于Swashbuckle.AspNetCore实现

【访问地址:http://localhost:1572/swagger/index.html】

1. 通过Nuget安装程序集【Swashbuckle.AspNetCore】,版本:4.0.1。

2. 将 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服务集合中。

复制代码

 1        public void ConfigureServices(IServiceCollection services)2         {3             services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);4 5             // 注册Swagger服务,声明一个或多个文档6             services.AddSwaggerGen(c =>7             {8                 c.SwaggerDoc("v1", new Info { Title = "Ypf API", Version = "v1" });9             });
10 
11         }

复制代码

3. 在 Startup.Configure 方法中,启用中间件为生成的 JSON 文档和 Swagger UI 提供服务。

复制代码

 1        public void Configure(IApplicationBuilder app, IHostingEnvironment env)2         {3             if (env.IsDevelopment())4             {5                 app.UseDeveloperExceptionPage();6             }7 8             // Enable middleware to serve generated Swagger as a JSON endpoint.9             app.UseSwagger();
10 
11             // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
12             // specifying the Swagger JSON endpoint.
13             app.UseSwaggerUI(c =>
14             {
15                 c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
16 
17                 //要在应用的根(http://localhost:<port>/) 处提供 Swagger UI,请将 RoutePrefix 属性设置为空字符串:
18                 //c.RoutePrefix = string.Empty;
19             });
20             app.UseMvc();
21         }

复制代码

  补充:配置完前三步后,通过访问【http://localhost:1572/swagger/v1/swagger.json】,返回一个json格式的文件。通过访问【http://localhost:1572/swagger/index.html】返回UI页面,这个时候发现UI页面中没有注释,很尴尬。

4. 开启注释

(1).选中当前项目,右键属性,进入“生成”页面,将“xml文档文件”的选项卡勾上。

(观察路径:D:\06-架构之路\05-DotNet Core体系\01-Asp.Net Core体系\05-CoreWebApi\OpenApiDemo\OpenApiDemo.xml,这里建议不要改了)

(2).去ConfigureServices中的AddSwaggerGen方法中,添加3行反射代码,与步骤1中的OpenApiDemo.xml关联起来。

复制代码

 1        public void ConfigureServices(IServiceCollection services)2         {3             services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);4 5             // 注册Swagger服务,声明一个或多个文档6             services.AddSwaggerGen(c =>7             {8                 c.SwaggerDoc("v1", new Info { Title = "Ypf API", Version = "v1" });9                 // 映射生成注释
10                 var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
11                 var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
12                 c.IncludeXmlComments(xmlPath);
13             });
14         }

复制代码

PS下技巧:

  开启注释以后,发现代码中很多提示没有加注释,而这些注释我是不想加的,那么怎么去掉呢,通过观察错误列表,发现这些提示都是CS1591,然后选中项目,右键属性,进入生成页面,在禁止显示错误警告的栏目中,加上“1591”即可解决。

 

5. 测试

  再次访问【http://localhost:1572/swagger/index.html】,发现注释都有了,可以开心的进行测试了,到这里已经大功告成了。

 

 

 

6.分享几个扩展功能

  (1).前面的openapi页面返回只有200即正常的说明,可以通过[ProducesResponseType(201)][ProducesResponseType(400)]特性,添加这两个状态的返回值, 加在下面的GetInfor1上。

 

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/438264.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

第十五节:Asp.Net Core MVC和WebApi路由规则的总结和对比-第二十节

一. Core Mvc 1.传统路由 Core MVC中&#xff0c;默认会在 Startup类→Configure方法→UseMvc方法中&#xff0c;会有默认路由&#xff1a;routes.MapRoute("default", "{controllerHome}/{actionIndex}/{id?}"); 等价于 app.UseMvcWithDefaultRoute(); …

String、StringBuffer和StringBuilde的区别

StringBuffer 和 StringBuilder 类提供了操作字符串的方法。 String为字符串常量&#xff0c;即String对象一旦创建之后该对象是不可更改&#xff0c;final 修饰&#xff0c;可以被不同线程共享&#xff0c;是线程安全的。在涉及多线程操作中不需要同步操作。 StringBuilder和…

第四节:Task的启动的四种方式以及Task、TaskFactory的线程等待和线程延续的解决方案

一. 背景 揭秘&#xff1a; 在前面的章节介绍过&#xff0c;Task出现之前&#xff0c;微软的多线程处理方式有&#xff1a;Thread→ThreadPool→委托的异步调用&#xff0c;虽然也可以基本业务需要的多线程场景&#xff0c;但它们在多个线程的等待处理方面、资源占用方面、线程…

Java中对字符串的操作

字符串反转 StringBuffer 或 StringBuilder 的 reverse方法 String s1 new StringBuilder(str).reverse().toString(); String s3 new StringBuffer(str).reverse().toString(); System.out.println(s1);//cba System.out.println(s3);//cbaList集合拼接成逗号分隔的字符串…

第五节:Task构造函数之TaskCreationOptions枚举处理父子线程之间的关系。

一. 整体说明 揭秘&#xff1a; 通过F12查看Task类的源码(详见下面的截图)&#xff0c;发现Task类的构造函数有有一个参数为&#xff1a;TaskCreationOptions类型&#xff0c;本章节可以算作是一个扩展章节&#xff0c;主要就来研究TaskCreationOptions类的作用。 该类主要用来…

List,Map,实体类,字符串相互转换

添加依赖 <dependency><groupId>com.alibaba</groupId><artifactId>fastjson</artifactId><version>1.2.7</version></dependency> List,实体类字符串想换转换 package Map;import com.alibaba.fastjson.*; import dto.Pers…

第六节:深入研究Task实例方法ContinueWith的参数TaskContinuationOptions

一. 整体说明 揭秘&#xff1a; 该章节的性质和上一个章节类似&#xff0c;也是一个扩展的章节&#xff0c;主要来研究Task类下的实例方法ContinueWith中的参数TaskContinuationOptions。 通过F12查看TaskContinuationOptions的源码&#xff0c;知道主要有这么几个参数&#xf…

java8 stream流操作集合交集,差集,并集,过滤,分组,去重,排序,聚合等

测试对象 public class Person {private String name;private Integer age;private Integer weight;public Person() {}public Integer getWeight() {return weight;}public void setWeight(Integer weight) {this.weight weight;}public Integer getAge() {return age…

第七节:利用CancellationTokenSource实现任务取消和利用CancellationToken类检测取消异常。

一. 传统的线程取消 所谓的线程取消&#xff0c;就是线程正在执行的过程中取消线程任务。 传统的线程取消&#xff0c;是通过一个变量来控制&#xff0c;但是这种方式&#xff0c;在release模式下&#xff0c;被优化从cpu高速缓存中读取&#xff0c;而不是从内存中读取&#xf…

start()和run()的区别

start方法&#xff1a; 通过该方法启动线程的同时也创建了一个线程&#xff0c;真正实现了多线程。无需等待run()方法中的代码执行完毕&#xff0c;就可以接着执行下面的代码。此时start()的这个线程处于就绪状态&#xff0c;当得到CPU的时间片后就会执行其中的run()方法。这个…

c#中的BeginInvoke和EndEndInvoke 摘要

摘要 异步这东西&#xff0c;真正用起来的时候&#xff0c;发现事情还是挺多的&#xff0c;最近在项目中用到了异步的知识&#xff0c;发现对它还是不了解&#xff0c;处理起来&#xff0c;走了不少弯路。觉得还是补一补还是很有必要的。 MSDN原文地址&#xff1a;https://ms…

关于@DateTimeFormat 和 @JsonFormat 注解

两个参数都是针对日期格式化做处理 1.入参格式化DateTimeFormat 传入参数是 String 类型,接收的参数Date 类型&#xff0c;类型无法转换。 使用 Spring 的 DateTimeFormat 注解格式化参数 传入参数要是日期格式的String 类型 例如:"2021-10-01" pattern &quo…

NET 提供了执行异步操作的三种模式

1.APM模式简介 在.net1.x的版本中就可以使用IAsyncResult接口实现异步操作&#xff0c;但是比较复杂&#xff0c;这种称之为异步编程模型模式 (Asynchronous Programming Model, APM)&#xff0c;也称为IAsyncResult模式 在这种APM模式下&#xff0c;一个同步操作XXX需要定义B…

java实体类属性非空判断工具类

import java.util.Collection; import java.util.HashMap; import java.util.Map; import java.util.Map.Entry;public class CheckParametersUtil {Map<String, Object> map new HashMap<>();/*** 添加需要校验的参数* param object 实参* param parameterName 参…

第八节:Task的各类TaskTResult返回值以及通用线程的异常处理方案。

一. Task的各种返回值-Task<TResult> PS&#xff1a; 在前面章节&#xff0c;我们介绍了Task类开启线程、线程等待、线程延续的方式&#xff0c;但我们并没有关注这些方式的返回值&#xff0c;其实他们都是有返回值的Task<TResult>&#xff0c;然后可以通过Task的…

第九节:深究并行编程Parallel类中的三大方法 (For、ForEach、Invoke)和几大编程模型(SPM、APM、EAP、TAP)

一. 并行编程 1. 区分串行编程和串行编程 ①. 串行编程&#xff1a;所谓的串行编程就是单线程的作用下&#xff0c;按顺序执行。(典型代表for循环 下面例子从1-100按顺序执行) ②. 并行编程&#xff1a;充分利用多核cpu的优势&#xff0c;同时开启多个线程并行执行。(典型代表…

Mybatis四种分页方式

1.数组分页 查询出全部数据&#xff0c;然后再list中截取需要的部分。 mybatis接口 List<Student> queryStudentsByArray(); xml配置文件 <select id"queryStudentsByArray" resultMap"studentmapper">select * from student</select&…

第十节:利用async和await简化异步编程模式的几种写法

一. async和await简介 PS&#xff1a;简介 1. async和await这两个关键字是为了简化异步编程模型而诞生的&#xff0c;使的异步编程更简洁&#xff0c;它本身并不创建新线程&#xff0c;但在该方法内部开启多线程&#xff0c;则另算。 2. 这两个关键字适用于处理一些文件IO操作。…

第十一节:深究用户模式锁的使用场景(异变结构、互锁、旋转锁)

一. 锁机制的背景介绍 本章节&#xff0c;将结合多线程来介绍锁机制&#xff0c; 那么问题来了&#xff0c;什么是锁呢&#xff1f; 为什么需要锁&#xff1f; 为什么要结合多线程来介绍锁呢&#xff1f;锁的使用场景又是什么呢&#xff1f; DotNet中又有哪些锁呢&#xff1f; …

第十三节:实际开发中使用最多的监视锁Monitor、lock语法糖的扩展、混合锁的使用(ManualResetEvent、SemaphoreSlim、ReaderWriterLockSlim)

一. 监视锁(Monitor和lock) 1. Monitor类&#xff0c;限定线程个数的一把锁&#xff08;Synchronized lock是他的语法糖&#xff09;&#xff0c;两个核心方法&#xff1a; Enter&#xff1a;锁住某个资源。 Exit&#xff1a;退出某一个资源。 测试案例&#xff1a;开启5个线…