第二十节: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 方法中的服务集合中。
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生成在线文档的更多相关文章
- asp.net webapi 生成在线文档--Swagger
第一步:使用nuget包获取Swashbule.swagger.net.ui的包并安装. 安装成功后 打开App_Start->SwaggerNet.cs 注释掉一下两行 //[assembly ...
- 在ASP.NET CORE下生成PDF文档
原文链接:https://www.c-sharpcorner.com/article/creating-pdf-in-asp-net-core-mvc-using-rotativa-aspnetcor ...
- 使用 Swagger 自动生成 ASP.NET Core Web API 的文档、在线帮助测试文档(ASP.NET Core Web API 自动生成文档)
对于开发人员来说,构建一个消费应用程序时去了解各种各样的 API 是一个巨大的挑战.在你的 Web API 项目中使用 Swagger 的 .NET Core 封装 Swashbuckle 可以帮助你 ...
- [.NET] WebApi 生成帮助文档及顺便自动创建简单的测试工具
==========最终的效果图========== ==========下面开始干活:生成帮助文档========== 一.创建 WebApi 项目 二.找到 HelpPageConfig.cs 并 ...
- apidoc快速生成在线文档,apidoc生成静态文件的生成规则以及原理分析
在老大的指引下,需要将系统的json文件格式转换成apidoc的json格式,也就是json格式的重组,但是这个apidoc的生成格式是不固定的,因为apidoc有自己一套的生成规则,我需要研究一下是 ...
- ASP.NET WebAPI 生成帮助文档与使用Swagger服务测试
帮助HELP 要实现如WCF中的Help帮助文档,Web API 2 中已经支持很方便的实现了这一特性 http://www.asp.net/web-api/overview/creating-we ...
- (转)WebApi自动生成在线文档WebApiTestClient
原文链接:http://www.cnblogs.com/landeanfen/p/5210356.html 前言:这两天在整WebApi的服务,由于调用方是Android客户端,Android开发人员 ...
- (转)WebApi自动生成在线文档Swashbuckle
原文地址:http://www.cnblogs.com/Arrays/p/5146194.html?utm_source=tuicool&utm_medium=referral 1.前言 1. ...
- 使用apidocJs快速生成在线文档
https://blog.csdn.net/xialei199023/article/details/63251482 https://blog.csdn.net/qq_16142851/articl ...
随机推荐
- 初学dubbo遇到的那些坑
昨天刚接触dubbo,遇到了一些坑,当然,这也与刚从eclipse换到了idea有一定的关系. 首先是maven仓库的问题,c盘下面的.m2文件夹默认的会被开发工具访问,所以要访问自己的本地仓库,.m ...
- Vue 拖拽组件 vuedraggable 和 vue-dragging
一.描述 之前用 vue 写过一个在线的多二维码生成服务,体验地址:https://postbird.gitee.io/vue-online-qrcode/ 后面发现二维码多了之后有时候想要排序,需要 ...
- ios视频网盘
http://pan.baidu.com/share/home?uk=1711799154#category/type=0
- Github使用教程图文详解
最近几天发现有些人对Github网站很好奇,但是无奈自己不会用,因为是外国人的网站,首先自己的英文就不过关.对于这个,其实可以用谷歌浏览器去浏览Github,它有一键翻译的功能.但还是有必要介绍一下关 ...
- MySQL的过滤(极客时间学习笔记)
数据过滤 SQL的数据过滤, 可以减少不必要的数据行, 从而可以达到提升查询效率的效果. 比较运算符 在SQL中, 使用WHERE子句对条件进行筛选, 筛选的时候比较运算符是很重要. 上面的比较运算符 ...
- bat弹出确认或取消窗口
需要在bat脚本里面弹出取消/确认框提示,可以用下面的案例: 示例: @echo off setlocal enabledelayedexpansion set Vbscript=Msgbox(&qu ...
- 奇怪的ifcfg-eth0被自动还原
最近,一台虚拟机是从外网下载的,然后导入本地测试环境使用. 发现一个奇怪的问题:修改了 /etc/sysconfig/network-scripts/ifcfg-eth0 保存后, 重启网络服务( s ...
- [TCP/IP] TCP在listen时的参数backlog的意义
linux内核中会维护两个队列: 1)未完成队列:接收到一个SYN建立连接请求,处于SYN_RCVD状态 2)已完成队列:已完成TCP三次握手过程,处于ESTABLISHED状态 3)当有一个S ...
- Python环境安装与基础语法(3)——进制、运算符和优先级、原码、补码
进制 转十进制:基本运算方法(权算方式) 0b1111——>1*2**3 + 1*2**2 + 1*2**1 + 1*2**0 0x7F——>7*16**1 + F*16**0 转二进制: ...
- JS中的实例方法、静态方法、实例属性、静态属性
一.静态方法与实例方法的例子: 我们先来看一个例子来看一下JS中的静态方法和实例方法到底是什么? 静态方法: function A(){} A.col='red' //静态属性 A.sayMeS=f ...