Gestion des versions dans Go Huma

Ce guide détaille la mise en œuvre de la documentation versionnée dans une API Go Huma. Nous créerons une documentation distincte pour chaque version de l'API (par exemple, /v1/docs, /v2/docs).

L'approche principale consiste à configurer le chemin de documentation et à utiliser un middleware pour charger dynamiquement le contenu de la documentation spécifique à la version.

Configuration :

Le DocsPath dans la configuration Huma dicte la structure de l'URL de la documentation. Nous l'avons défini sur /{version}/docs pour s'adapter aux préfixes de version :

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

Middleware pour la gestion des versions :

Le middleware intercepte les requêtes pour déterminer la version de l'API à partir du chemin URL et charge la documentation correspondante. Cet exemple utilise un chi routeur :

<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>

Ce middleware extrait la version, lit le fichier overview.md correspondant (ajustez le chemin si nécessaire), définit la description dans la configuration Huma, puis enregistre les gestionnaires appropriés pour cette version. La gestion des erreurs est améliorée pour fournir des réponses plus informatives. Notez la gestion explicite de la version 3 et un cas par défaut pour les versions non prises en charge. N'oubliez pas de remplacer les espaces réservés tels que v1handlers, v2handlers, v3handlers et helpers.Contains par vos implémentations réelles. La fonction helpers.Contains doit vérifier si une chaîne existe dans une tranche de chaînes.

Cette configuration garantit que la documentation correcte est fournie en fonction de la version de l'API demandée. Pensez à créer les docs/v{version}/overview.md fichiers pour chaque version.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!