第十四节：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上。

第十四节：Asp.Net Core WebApi生成在线文档-第十九节相关推荐

第十三节：Asp.Net Core WebApi基础总结和请求方式-第十八节
一. 基础总结 1.Restful服务改造 Core下的WebApi默认也是Restful格式服务,即通过请求方式(Get,post,put,delete)来区分请求哪个方法,请求的URL中不需要写方 ...
使用ASP.NET Core进行跨平台Web文档扫描
如果您是C#开发人员,可以使用哪种技术来创建跨平台的Web文档扫描应用程序? 答案是ASP.NET Core和Dynamic Web TWAIN. 在这篇文章中,我将分享如何使用这些技术从头开始构建一 ...
ASP.NET Core WebApi构建API接口服务实战演练
一.ASP.NET Core WebApi课程介绍人生苦短,我用.NET Core!提到Api接口,一般会想到以前用到的WebService和WCF服务,这三个技术都是用来创建服务接口,只不过Web ...
IIS部署asp.net core webapi
一.需要安装Windows Server Hosting,作用是让IIS有方向代理功能(Asp.Net Core Module负责反向代理工作),将请求转发到Kestrel,Windows serve ...
ASP.Net Core WebApi几种版本控制对比
ASP.Net Core WebApi几种版本控制对比原文:ASP.Net Core WebApi几种版本控制对比一.版本控制的好处: (1)有助于及时推出功能, 而不会破坏现有系统. (2)它还 ...
Asp.Net Core WebAPI+PostgreSQL部署在Docker中
PostgreSQL是一个功能强大的开源数据库系统.它支持了大多数的SQL:2008标准的数据类型,包括整型.数值值.布尔型.字节型.字符型.日期型.时间间隔型和时间型,它也支持存储二进制的大对像,包 ...
asp.net core WebAPI实现CRUD
本节用于构建一个简单的WebAPI来管理to-do列表.不会创建用户界面. API Description Request body Response body GET /api/todo Get a ...
NET问答: 如何将 ASP.NET Core WebAPI 中抛出的异常封装成对象？
咨询区 rianjs: 在 ASP.NET Core WebAPI 中,我的 Controller 代码如下: [Route("create-license/{licenseKey}&quo ...
【源码解读】Vue与ASP.NET Core WebAPI的集成
在前面博文[Vue]Vue 与 ASP.NET Core WebAPI 的集成中,介绍了集成原理:在中间件管道中注册SPA终端中间件,整个注册过程中,终端中间件会调用node,执行npm start命 ...

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

第十四节：Asp.Net Core WebApi生成在线文档-第十九节相关推荐

最新文章

热门文章