NetCore 使用 Swashbuckle 搭建 SwaggerHub

小朱朱

什么是SwaggerHub?

Hub 谓之 中心, 所以 SwaggerHub即swagger中心.
什么时候需要它?

通常, 公司都拥有多个服务, 例如商品服务, 订单服务, 用户服务, 等等, 每个服务都有自己的environment, endpoint, swagger schema. 然而这些信息都分散在各处, 如果能集中在一个地方展示出来, 就能减少许多无意义的沟通协作, 另外也可以有更有全局视野查看整个公司的API's.
成熟的商业产品.

例如 https://swagger.io/tools/swaggerhub/, 不光可以做Hub, 还有很多其他的管理功能, 实时的编辑器, 版本管理等等.
商业产品功能很好, 但是要钱.
所以... 我们可以...
使用 Swashbuckle.Swagger 搭建SwaggerHub.

在NetCore的世界里, 我们可以使用 Swashbuckle.AspNetCore来构建一个我们自己的SwaggerHub. 而且特别简单, 我们仅需要一行代码即可

1. var swaggerUIOptions = new SwaggerUIOptions();
2. swaggerUIOptions.ConfigObject.Urls = new[] {
3.     new UrlDescriptor() {
4.         Name = "swagger name",
5.         Url= "swagger.json"
6.     }
7. };
9. app.UseSwaggerUI(swaggerUIOptions);

复制代码

我们只需要配置Urlsoption, 增加多个swagger json 配置就完事儿了, 如此, Hub就完成了. 本文章到这里也就算完事儿了.
剩下的就是根据公司情况如同, 采用的方案不同而要解决的一些实际问题了.
对swaggerUIOptions的改动是实时生效的.

对swaggerUIOptions对象的任何更改都是实时生效的, 所以我们可以做到只要改配置即可实时生效.
Url 可以配置为一个endpoint, 直接由swaggerui在浏览器中下载指定的文件.

1. new UrlDescriptor(){Url="https://www.cnblogs.com/swagger.json"}

复制代码

Url 也可以是在任何地方的一个文件

1. //配置url从当前项目的一个地址下载文件.
2. new UrlDescriptor(){Url="/swagger-file/swagger.json"}
4. // 从本地读取swagger文件
5. [HttpGet("/swagger-file/{swaggerName}.json")]
6. public IActionResult GetSwaggerFileAsync([FromRoute] string swaggerName)
7. {
8.     return this.File($"static-file-dir/swaggers/{serviceName}.json", "application/json");
9. }

复制代码

当然, 我们也可以读取任何地方的swagger文件, 例如在github, 各种云存储(aws/s3, aliyun/oss)等等.
为每一个swagger配置server地址.

每个swagger可能代表这不同的服务, 大概率就有不同的endpoint, 也可以是多个环境配置地址(dev,uat,staging,pro).
给swagger.json增加servers节点即可.

1. {
2.     "servers":["server-endpoint1","server-endpoint2"]
3. }

复制代码

可以使用各个JSON组件动态插入, 也可以用Microsoft.OpenApi.Readers 组件来解析和改写所有swagger的内容

1. var doc = new OpenApiStreamReader().Read(sourceSwaggerJson, out _);
2. doc.Servers.Add(new OpenApiServer() { Url = "my-dev-server-endpoint" });
3. doc.Servers.Add(new OpenApiServer() { Url = "my-pro-server-endpoint" });
4. string swaggerJsonContent = targetDoc.SerializeAsJson(Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_0);

复制代码

Microsoft.OpenApi.Readers 可以用来解析openAPI 格式的文档. 支持v2,v3等版本, 支持json,yaml格式. 详情可查看官方文档. 所以这个netcore 的 swaggerhub 自然而然的就支持读取任何语言支持的openAPI文档(java, nodejs, 等等).
合并多个swagger文档到一个swagger文档

单一的一个服务由多个不同的服务提供服务支持. 举个例子, 商品服务由商品服务+商品搜索服务共同组成, 2个单独的服务由2个单独的team负责维护, 但是对外提供服务的时候暴露在同一个domian下, 根据path route到不同的服务上. 这个时候我们还是使用Microsoft.OpenApi.Readers 来做合并这个事情.

1. //demo代码
2. var productDoc= download();
3. var productSearchDoc= download();
4. var targetDoc = new OpenApiDocument() { Components = new(), Paths = new() };
6. targetDoc.Paths.Add(productDoc.Paths)
7. targetDoc.Paths.Add(productSearchDoc.Paths)
8. targetDoc.Components.Schemas.Add(...)
9. //巴拉巴拉
10. string swaggerJsonContent = targetDoc.SerializeAsJson(Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_0);

复制代码

上面只是列出了我碰到的几个具体情况, 不同的公司不同的场景下还有更多可能的case. 这个就得case by case了. 但是一个万变不离其宗, 总之就是对openAPI生成是swagger文件进行自定义. 这个时候用Microsoft.OpenApi.Readers就完事了.
综上,
SwaggerHub, SwaggerUI 用Swashbuckle.AspNetCore搭建.
OpenAPI Swagger Doc 用Microsoft.OpenApi.Readers做定制化修改.

来源:https://www.cnblogs.com/calvinK/archive/2023/04/03/netcore-buiding-swaggerhub.html
免责声明：由于采集信息均来自互联网，如果侵犯了您的权益，请联系我们【E-Mail:cb@itdo.tech】 我们会及时删除侵权内容，谢谢合作！