什麼是SwaggerHub? Hub 謂之 中心, 所以 SwaggerHub即swagger中心. 什麼時候需要它? 通常, 公司都擁有多個服務, 例如商品服務, 訂單服務, 用戶服務, 等等, 每個服務都有自己的environment, endpoint, swagger schema. 然而這 ...
什麼是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做定製化修改.
