.NET Core 中的 Swagger 应用与微服务场景下的Swagger Api 集成显示
Swagger 与 OpenAPI 的历史来源:
Swagger 项目于 2015 年捐赠给 OpenAPI Initiative,此后被称为 OpenAPI。这两个名称可以互换使用。但是,“OpenAPI”指的是规范。“Swagger”是指来自 SmartBear 的符合 OpenAPI 规范的开源和商业产品系列。
简而言之:
- OpenAPI 是一种规范。
- Swagger 是使用 OpenAPI 规范的工具。例如,OpenAPIGenerator 和 SwaggerUI。
1. OpenAPI
OpenAPI 规范用于描述api的基本信息及功能。比如,API支持的http 方法,响应结果skema, 响应状态码等等。OpenAPI的声明定义方式可以通过json 和 yaml的方式,以下是通过yaml 描述api的一个基本例子。
openapi: 3.0.0
info:
title: Sample API
description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
version: 0.1.9
servers:
- url: http://api.example.com/v1
description: Optional server description, e.g. Main (production) server
- url: http://staging-api.example.com
description: Optional server description, e.g. Internal staging server for testing
paths:
/users:
get:
summary: Returns a list of users.
description: Optional extended description in CommonMark or HTML.
responses:
'200': # status code
description: A JSON array of user names
content:
application/json:
schema:
type: array
items:
type: string
2. 单个项目中集成 Swashbuckle
Swashbuckle 包含三个主要组件:
Swashbuckle.AspNetCore.Swagger:Swagger 对象模型和中间件,用于将
SwaggerDocument
对象公开为 JSON 端点。Swashbuckle.AspNetCore.SwaggerGen:一个 Swagger 生成器,可
SwaggerDocument
直接从您的路由、控制器和模型构建对象。它通常与 Swagger 端点中间件结合使用以自动公开 Swagger JSON。Swashbuckle.AspNetCore.SwaggerUI:Swagger UI 工具的嵌入式版本。它解释 Swagger JSON 以构建丰富的、可定制的体验来描述 Web API 功能。它包括用于公共方法的内置测试工具。
Basic 用法:
将 Swagger 生成器添加到方法中的服务集合中Startup.ConfigureServices
public void ConfigureServices(IServiceCollection services)
{ // Register the Swagger generator, defining 1 or more Swagger documents
services.AddSwaggerGen();
}
在该Startup.Configure
方法中,启用中间件以提供生成的 JSON 文档和 Swagger UI:
public void Configure(IApplicationBuilder app)
{
// 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");
}); ......
}
详细的Swagger 文档
在AddSwaggerGen 时,我们可以向其中传入参数 Action<SwaggerGenOptions> 这个参数,来声明我们如何创建OpenAPI 文档来描述我们的api。
services.AddSwaggerGen(c =>
{
//声明文档的名字, title, version 等基本信息
c.SwaggerDoc("v1", new OpenApiInfo { Title = "My Example APIs", Version = "v1" });
c.CustomSchemaIds((type) => type.FullName);
// 通过path 判断哪些api 应该被显示在文档上
c.DocInclusionPredicate((docName, apiDescription) => apiDescription.RelativePath.Contains("api/v1"));
// 包含描述性的 xml 文档
var xmlDoc = Path.Combine(AppContext.BaseDirectory, $"{this.GetType().Assembly.GetName().Name}.XML");
if (File.Exists(xmlDoc))
c.IncludeXmlComments(xmlDoc);
});
3. 微服务多应用的Swagger用法
我们在之前的例子中,一直是对单个应用的单个文档,那么对于多个应用的文档,我们如何集中显示,方便开发人员查找与使用。
既然UseSwagger这个中间件可以帮助我们host生成的swagger json 文件,那么是不是我们通过一个application(api-explorer)来显示各个appplication的文档就可以,这能做到么?
答案是: 利用swagger的UI 前端文件。
这里给一个最basic的实现,使用的时候,可以各种定制化样式,加入请求验证等等;
<script src="./swagger-ui-bundle.js"> </script>
<script>
const apis = config.urls.sort((a, b) => a.name.localeCompare(b.name));
jwtToken = `Bearer ${token}`;
const ui = SwaggerUIBundle({
// 重中之重
urls: [{url, name}],
dom_id: '#swagger-ui',
deepLinking: true,
// Add jwt token to header start
requestInterceptor: function(request) {
request.headers.Authorization = jwtToken;
return request;
},
// Add jwt token to header finish layout: "StandaloneLayout"
})
window.ui = ui;
})
}
</script>
我们可以通过配置文件的形式,注册好各个application的url,和它们各自的名字。
[{url: '/a/a', name: 'aa'}, {url: '/b/b', name: 'bb'}] 这种形式。
SwaggerUI 和 SwaggerUI bundle 可以接受的参数如链接,大家可以找到自己需要的参数去配置需要的功能。
https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md
-----------------------------------------------------------------------------------------------------------------------------------------------------
欢迎大家讨论交流,指出不足,谢谢!
.NET Core 中的 Swagger 应用与微服务场景下的Swagger Api 集成显示的更多相关文章
- CI Weekly #11 | 微服务场景下的自动化测试与持续部署
又一周过去了,最近我们的工程师正在搞一个"大事情" --「[flow.ci](http://flow.ci/?utm_source=bokeyuan&utm_medium= ...
- TOP100summit:【分享实录-华为】微服务场景下的性能提升最佳实践
本篇文章内容来自2016年TOP100summit华为架构部资深架构师王启军的案例分享.编辑:Cynthia 王启军:华为架构部资深架构师.负责华为的云化.微服务架构推进落地,前后参与了华为手机祥云4 ...
- 【星云测试】Devops微服务架构下具有代码级穿透能力的精准测试
微服务是Devops场景下热门的开发框架,在大型项目中被广泛采用.它把一个大型的单个应用程序和服务拆分为数十个的支持微服务,独立部署.互相隔离,通过扩展组件来处理功能瓶颈问题,比传统的应用程序更能有效 ...
- 微服务架构下 CI/CD 如何落地
本文系云原生应用最佳实践杭州站活动演讲稿整理.杭州站活动邀请了 Apache APISIX 项目 VP 温铭.又拍云平台开发部高级工程师莫红波.蚂蚁金服技术专家王发康.有赞中间件开发工程师张超,分享云 ...
- .NET Core微服务之基于Ocelot实现API网关服务
Tip: 此篇已加入.NET Core微服务基础系列文章索引 一.啥是API网关? API 网关一般放到微服务的最前端,并且要让API 网关变成由应用所发起的每个请求的入口.这样就可以明显的简化客户端 ...
- 微服务框架下的思维变化-OSS.Core基础思路
如今框架两字已经烂大街了,xx公司架构设计随处可见,不过大多看个热闹,这些框架如何来的,细节又是如何思考的,相互之间的隔离依据又是什么...相信很多朋友应该依然存在自己的疑惑,特别是越来越火热的微服务 ...
- 微服务:springboot与swagger2的集成
现在测试都提倡自动化测试,那我们作为后台的开发人员,也得进步下啊,以前用postman来测试后台接口,那个麻烦啊,一个字母输错就导致测试失败,现在swagger的出现可谓是拯救了这些开发人员,便捷之处 ...
- CI Weekly #5 | 微服务架构下的持续部署与交付
CI Weekly 围绕『 软件工程效率提升』 进行一系列技术内容分享,包括国内外持续集成.持续交付,持续部署.自动化测试. DevOps 等实践教程.工具与资源,以及一些工程师文化相关的程序员 Ti ...
- 微服务架构下分布式Session管理
转载本文需注明出处:EAII企业架构创新研究院(微信号:eaworld),违者必究.如需加入微信群参与微课堂.架构设计与讨论直播请直接回复此公众号:“加群 姓名 公司 职位 微信号”. 一.应用架构变 ...
随机推荐
- 深度人脸识别:CVPR2020论文要点
深度人脸识别:CVPR2020论文要点 Towards Universal Representation Learning for Deep Face Recognition 论文链接:https:/ ...
- 降维-基于RDD的API
降维-基于RDD的API Singular value decomposition (SVD) Performance SVD Example Principal component analysis ...
- 将TVM集成到PyTorch上
将TVM集成到PyTorch上 随着TVM不断展示出对深度学习执行效率的改进,很明显PyTorch将从直接利用编译器堆栈中受益.PyTorch的主要宗旨是提供无缝且强大的集成,而这不会妨碍用户.为此, ...
- Yolo:实时目标检测实战(上)
Yolo:实时目标检测实战(上) YOLO:Real-Time Object Detection 你只看一次(YOLO)是一个最先进的实时物体检测系统.在帕斯卡泰坦X上,它以每秒30帧的速度处理图像, ...
- springmvc——自定义类型转换器
一.什么是springmvc类型转换器? 在我们的ssm框架中,前端传递过来的参数都是字符串,在controller层接收参数的时候springmvc能够帮我们将大部分字符串类型的参数自动转换为我们指 ...
- 基于Android平台的图书管理系统的制作(4)
讲解完学生.职员.书籍这些基础层之后,我们可以来了解一些应用层的活动. 新书上架.借阅排行.黑名单.图书馆介绍.图书馆新闻. 新书上架是查询数据库里的Book表,将最近注册的五本书的基本信息(若图书馆 ...
- Linux Oracle 中文乱码解决
1.Linux操作系统Oracle11g设置别名的时候发现中文乱码 2.直接修改环境变量 添加 export NLS_LANG=AMERICAN_AMERICA.ZHS16GBK 3.执行命令使环境变 ...
- 为什么 Python 没有函数重载?如何用装饰器实现函数重载?
英文:https://arpitbhayani.me/blogs/function-overloading 作者:arprit 译者:豌豆花下猫("Python猫"公众号作者) 声 ...
- ceph-csi源码分析(2)-组件启动参数分析
更多ceph-csi其他源码分析,请查看下面这篇博文:kubernetes ceph-csi分析目录导航 ceph-csi源码分析(2)-组件启动参数分析 ceph-csi组件的源码分析分为五部分: ...
- k8s-生产环境部署django项目k8s-dashboard管理系统
1. k8s-生产环境部署django项目k8s-dashboard管理系统 gitee地址: https://gitee.com/scajy/django-k8s-dashboard.git 部署架 ...