Go Huma 中的版本控制

本指南詳細介紹了在 Go Huma API 中實作版本化文件。 我們將為每個 API 版本建立單獨的文件（例如 /v1/docs、/v2/docs）。

核心方法包括設定文件路徑和使用中介軟體動態載入特定版本的文件內容。

設定：

Huma 配置中的 DocsPath 規定了文件 URL 結構。 我們將其設為 /{version}/docs 以適應版本前綴：

<code class="language-go">config.DocsPath = "/{version}/docs"</code>

版本處理中間件：

中間件攔截請求，從 URL 路徑確定 API 版本並載入對應的文件。 此範例使用 chi 路由器：

<code class="language-go">router := chi.NewMux()
router.Use(func(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        urlPathParts := strings.Split(r.URL.Path, "/")
        versions := []string{"v1", "v2", "v3"} // Supported versions

        if helpers.Contains(versions, urlPathParts[1]) { // Check if a valid version is present
            versionPath := urlPathParts[1]
            versionNumberString := strings.TrimPrefix(versionPath, "v")
            versionNumber, _ := strconv.Atoi(versionNumberString)

            config := huma.DefaultConfig("API V"+versionNumberString, versionNumberString+".0.0")
            overviewFilePath := fmt.Sprintf("docs/v%s/overview.md", versionNumberString) // Path to version-specific overview

            overview, err := ioutil.ReadFile(overviewFilePath)
            if err != nil {
                http.Error(w, fmt.Sprintf("Error reading documentation: %v", err), http.StatusInternalServerError) //Improved error handling
                return
            }

            config.Info.Description = string(overview)
            api := humachi.New(router, config)

            switch versionNumber {
            case 1:
                api = v1handlers.AddV1Middleware(api)
                v1handlers.AddV1Routes(api)
            case 2:
                api = v2handlers.AddV2Middleware(api)
                v2handlers.AddV2Routes(api)
            case 3: //Explicitly handle version 3
                api = v3handlers.AddV3Middleware(api)
                router = v3handlers.AddV3ErrorResponses(router) //Handle error responses separately if needed
                v3handlers.AddV3Routes(api)
            default:
                http.Error(w, "Unsupported API version", http.StatusBadRequest) //Handle unsupported versions
                return
            }
        }

        next.ServeHTTP(w, r)
    })
})

//Final Huma config (for default/fallback behavior if no version is specified)
config := huma.DefaultConfig("API V3", "3.0.0")
config.DocsPath = "/{version}/docs"
humachi.New(router, config)</code>

此中間件擷取版本，讀取對應的 overview.md 檔案（根據需要調整路徑），在 Huma 配置中設定描述，然後為該版本註冊適當的處理程序。 改進了錯誤處理以提供更多資訊的回應。 請注意版本 3 的明確處理以及不支援版本的預設情況。 請記得將 v1handlers、v2handlers、v3handlers 和 helpers.Contains 等佔位符替換為您的實際實作。 helpers.Contains 函數應該檢查字串切片中是否存在字串。

此設定可確保根據要求的 API 版本提供正確的文件。 請記住為每個版本建立 docs/v{version}/overview.md 檔案。

以上是Go Huma 中的版本控制的詳細內容。更多資訊請關注PHP中文網其他相關文章！