什么是SwaggerHub?
中心, 所以 SwaggerHub即swagger中心。
什么时候需要它?
成熟的商业产品.
例如 https://swagger.io/tools/swaggerhub/, 不光可以做Hub, 还有很多其他的管理功能, 实时的编辑器, 版本管理等等.
商业产品功能很好, 但是要钱.
所以... 我们可以..。
使用 Swashbuckle.Swagger 搭建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.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文档
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做定制化修改。