本指南詳細介紹了在 Go Huma API 中實現(xiàn)版本化文檔。 我們將為每個 API 版本創(chuàng)建單獨的文檔（例如 /v1/docs、/v2/docs）。

核心方法包括配置文檔路徑和使用中間件動態(tài)加載特定版本的文檔內(nèi)容。

配置：

Huma 配置中的 DocsPath 規(guī)定了文檔 URL 結(jié)構(gòu)。 我們將其設(shè)置為 /{version}/docs 以適應版本前綴：

config.DocsPath = "/{version}/docs"

版本處理中間件：

中間件攔截請求，從 URL 路徑確定 API 版本并加載相應的文檔。 此示例使用 chi 路由器：

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)

該中間件提取版本，讀取相應的 overview.md 文件（根據(jù)需要調(diào)整路徑），在 Huma 配置中設(shè)置描述，然后為該版本注冊適當?shù)奶幚沓绦颉? 改進了錯誤處理以提供更多信息的響應。 請注意版本 3 的顯式處理以及不受支持版本的默認情況。 請記住將 v1handlers、v2handlers、v3handlers 和 helpers.Contains 等占位符替換為您的實際實現(xiàn)。 helpers.Contains 函數(shù)應該檢查字符串切片中是否存在字符串。

此設(shè)置可確保根據(jù)請求的 API 版本提供正確的文檔。 請記住為每個版本創(chuàng)建 docs/v{version}/overview.md 文件。

以上是Go Huma 中的版本控制的詳細內(nèi)容。更多信息請關(guān)注PHP中文網(wǎng)其他相關(guān)文章！