Versioning in Go Huma

This guide details implementing versioned documentation in a Go Huma API. We'll create separate documentation for each API version (e.g., /v1/docs, /v2/docs).

The core approach involves configuring the documentation path and using middleware to dynamically load version-specific documentation content.

Configuration:

The DocsPath in the Huma configuration dictates the documentation URL structure. We set it to /{version}/docs to accommodate version prefixes:

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

Middleware for Version Handling:

Middleware intercepts requests to determine the API version from the URL path and loads the corresponding documentation. This example uses a chi router:

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)

This middleware extracts the version, reads the corresponding overview.md file (adjust the path as needed), sets the description in the Huma config, and then registers the appropriate handlers for that version. Error handling is improved to provide more informative responses. Note the explicit handling of version 3 and a default case for unsupported versions. Remember to replace placeholders like v1handlers, v2handlers, v3handlers, and helpers.Contains with your actual implementations. The helpers.Contains function should check if a string exists in a slice of strings.

This setup ensures that the correct documentation is served based on the requested API version. Remember to create the docs/v{version}/overview.md files for each version.

The above is the detailed content of Versioning in Go Huma. For more information, please follow other related articles on the PHP Chinese website!