Go Huma 中的版本控制

本指南详细介绍了在 Go Huma API 中实现版本化文档。 我们将为每个 API 版本创建单独的文档（例如 /v1/docs、/v2/docs）。

核心方法包括配置文档路径和使用中间件动态加载特定版本的文档内容。

配置：

Huma 配置中的 DocsPath 规定了文档 URL 结构。 我们将其设置为 /{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 文件（根据需要调整路径），在 Huma 配置中设置描述，然后为该版本注册适当的处理程序。 改进了错误处理以提供更多信息的响应。 请注意版本 3 的显式处理以及不受支持版本的默认情况。 请记住将 v1handlers、v2handlers、v3handlers 和 helpers.Contains 等占位符替换为您的实际实现。 helpers.Contains 函数应该检查字符串切片中是否存在字符串。

此设置可确保根据请求的 API 版本提供正确的文档。 请记住为每个版本创建 docs/v{version}/overview.md 文件。

以上是Go Huma 中的版本控制的详细内容。更多信息请关注PHP中文网其他相关文章！