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. 而且特别简单, 我们仅需要一行代码即可
var swaggerUIOptions = new SwaggerUIOptions();
swaggerUIOptions.ConfigObject.Urls = new[] {
new UrlDescriptor() {
Name = "swagger name",
Url= "swagger.json"
}
};
app.UseSwaggerUI(swaggerUIOptions);
我们只需要配置Urlsoption, 增加多个swagger json 配置就完事儿了, 如此, Hub就完成了. 本文章到这里也就算完事儿了.
剩下的就是根据公司情况如同, 采用的方案不同而要解决的一些实际问题了.
对swaggerUIOptions的改动是实时生效的.
对swaggerUIOptions对象的任何更改都是实时生效的, 所以我们可以做到只要改配置即可实时生效.
Url 可以配置为一个endpoint, 直接由swaggerui在浏览器中下载指定的文件.
new UrlDescriptor(){Url="https://www.cnblogs.com/swagger.json"}
Url 也可以是在任何地方的一个文件
//配置url从当前项目的一个地址下载文件.
new UrlDescriptor(){Url="/swagger-file/swagger.json"}
// 从本地读取swagger文件
[HttpGet("/swagger-file/{swaggerName}.json")]
public IActionResult GetSwaggerFileAsync([FromRoute] string swaggerName)
{
return this.File($"static-file-dir/swaggers/{serviceName}.json", "application/json");
}
当然, 我们也可以读取任何地方的swagger文件, 例如在github, 各种云存储(aws/s3, aliyun/oss)等等.
为每一个swagger配置server地址.
每个swagger可能代表这不同的服务, 大概率就有不同的endpoint, 也可以是多个环境配置地址(dev,uat,staging,pro).
给swagger.json增加servers节点即可.
{
"servers":["server-endpoint1","server-endpoint2"]
}
可以使用各个JSON组件动态插入, 也可以用Microsoft.OpenApi.Readers 组件来解析和改写所有swagger的内容
var doc = new OpenApiStreamReader().Read(sourceSwaggerJson, out _);
doc.Servers.Add(new OpenApiServer() { Url = "my-dev-server-endpoint" });
doc.Servers.Add(new OpenApiServer() { Url = "my-pro-server-endpoint" });
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 来做合并这个事情.
//demo代码
var productDoc= download();
var productSearchDoc= download();
var targetDoc = new OpenApiDocument() { Components = new(), Paths = new() };
targetDoc.Paths.Add(productDoc.Paths)
targetDoc.Paths.Add(productSearchDoc.Paths)
targetDoc.Components.Schemas.Add(...)
//巴拉巴拉
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做定制化修改.