一. 基本概念

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 方法中的服务集合中。

        public void ConfigureServices(IServiceCollection services)
{
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2); // 注册Swagger服务,声明一个或多个文档
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info { Title = "Ypf API", Version = "v1" });
}); }

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

        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
} // Enable middleware to serve generated Swagger as a JSON endpoint.
app.UseSwagger(); // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.),
// specifying the Swagger JSON endpoint.
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); //要在应用的根(http://localhost:<port>/) 处提供 Swagger UI,请将 RoutePrefix 属性设置为空字符串:
//c.RoutePrefix = string.Empty;
});
app.UseMvc();
}

  补充:配置完前三步后,通过访问【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关联起来。

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

PS下技巧:

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

5. 测试

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

6.分享几个扩展功能

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

!

  • 作       者 : Yaopengfei(姚鹏飞)
  • 博客地址 : http://www.cnblogs.com/yaopengfei/
  • 声     明1 : 本人才疏学浅,用郭德纲的话说“我是一个小学生”,如有错误,欢迎讨论,请勿谩骂^_^。
  • 声     明2 : 原创博客请在转载时保留原文链接或在文章开头加上本人博客地址,否则保留追究法律责任的权利。
 

第二十节:Asp.Net Core WebApi生成在线文档的更多相关文章

  1. asp.net webapi 生成在线文档--Swagger

    第一步:使用nuget包获取Swashbule.swagger.net.ui的包并安装. 安装成功后 打开App_Start->SwaggerNet.cs 注释掉一下两行 //[assembly ...

  2. 在ASP.NET CORE下生成PDF文档

    原文链接:https://www.c-sharpcorner.com/article/creating-pdf-in-asp-net-core-mvc-using-rotativa-aspnetcor ...

  3. 使用 Swagger 自动生成 ASP.NET Core Web API 的文档、在线帮助测试文档(ASP.NET Core Web API 自动生成文档)

    对于开发人员来说,构建一个消费应用程序时去了解各种各样的 API 是一个巨大的挑战.在你的 Web API 项目中使用 Swagger 的 .NET Core 封装 Swashbuckle 可以帮助你 ...

  4. [.NET] WebApi 生成帮助文档及顺便自动创建简单的测试工具

    ==========最终的效果图========== ==========下面开始干活:生成帮助文档========== 一.创建 WebApi 项目 二.找到 HelpPageConfig.cs 并 ...

  5. apidoc快速生成在线文档,apidoc生成静态文件的生成规则以及原理分析

    在老大的指引下,需要将系统的json文件格式转换成apidoc的json格式,也就是json格式的重组,但是这个apidoc的生成格式是不固定的,因为apidoc有自己一套的生成规则,我需要研究一下是 ...

  6. ASP.NET WebAPI 生成帮助文档与使用Swagger服务测试

    帮助HELP 要实现如WCF中的Help帮助文档,Web API 2 中已经支持很方便的实现了这一特性  http://www.asp.net/web-api/overview/creating-we ...

  7. (转)WebApi自动生成在线文档WebApiTestClient

    原文链接:http://www.cnblogs.com/landeanfen/p/5210356.html 前言:这两天在整WebApi的服务,由于调用方是Android客户端,Android开发人员 ...

  8. (转)WebApi自动生成在线文档Swashbuckle

    原文地址:http://www.cnblogs.com/Arrays/p/5146194.html?utm_source=tuicool&utm_medium=referral 1.前言 1. ...

  9. 使用apidocJs快速生成在线文档

    https://blog.csdn.net/xialei199023/article/details/63251482 https://blog.csdn.net/qq_16142851/articl ...

随机推荐

  1. SPC软控件提供商NWA的产品在各行业的应用(石油天然气行业)

    Northwest Analytical (NWA)是全球领先的“工业4.0”制造分析SPC软件控件提供商.产品(包含: NWA Quality Analyst , NWA Focus EMI 和 N ...

  2. android studio学习----自动导包

    介绍一个最有用的设置,我们只有每次引用一些类的时候必须要导包,而Studio可以通过设置自动导包,简直太实用了. 到 Preferences -> Editor -> Auto Impor ...

  3. itextpdf5单元格中的段落没有行间距

    关于对表格中的段落没有行间距的解决方式:通过观察和推测的结论:itextpdf对一些属性,只会对最外层元素的属性进行接收处理,如行间距.例: Paragraph p = new Paragraph(1 ...

  4. Linux 用libevent实现的简单http服务器

    Linux 用libevent实现的简单http服务器 main.c #include <stdio.h> #include <sys/types.h> #include &l ...

  5. PHP数组相关算法

    一.排序算法 1. 冒泡排序 2. 选择排序 二.查找算法 1. 遍历 2. 二分查找

  6. Linux内核调试的方式以及工具集锦【转】

    转自:https://blog.csdn.net/gatieme/article/details/68948080 版权声明:本文为博主原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原 ...

  7. 006-OpenStack-配仪表盘

    OpenStack-配仪表盘 [基于此文章的环境]点我快速打开文章 计算节点安装(compute1) 1.安装 yum install openstack-dashboard -y &> ...

  8. Rocketmq原理&最佳实践

    MQ背景&选型 消息队列作为高并发系统的核心组件之一,能够帮助业务系统解构提升开发效率和系统稳定性.主要具有以下优势: 削峰填谷(主要解决瞬时写压力大于应用服务能力导致消息丢失.系统奔溃等问题 ...

  9. robotframework-post request请求携带上一个请求返回的cookie

    公司的接口服务需要先登录,获取服务端的cookie后,在后续的请求中携带这个cookie才能够访问 在尝试用RF工具进行自动化接口测试时,发现先访问登录接口之后,接着请求其他接口时没有自动携带上次请求 ...

  10. npm安装使用^符号时,在0.0.1等版本下区别

    文档地址 https://docs.npmjs.com/misc/semver Caret Ranges ^1.2.3 ^0.2.5 ^0.0.4§ Allows changes that do no ...