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做客製化化修改.