Versionierung in Go Huma

Diese Anleitung beschreibt die Implementierung versionierter Dokumentation in einer Go Huma API. Wir erstellen für jede API-Version eine separate Dokumentation (z. B. /v1/docs, /v2/docs).

Der Kernansatz besteht darin, den Dokumentationspfad zu konfigurieren und Middleware zu verwenden, um versionenspezifische Dokumentationsinhalte dynamisch zu laden.

Konfiguration:

Das DocsPath in der Huma-Konfiguration bestimmt die URL-Struktur der Dokumentation. Wir setzen es auf /{version}/docs, um Versionspräfixe zu berücksichtigen:

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

Middleware für die Versionsverwaltung:

Middleware fängt Anfragen zur Ermittlung der API-Version anhand des URL-Pfads ab und lädt die entsprechende Dokumentation. In diesem Beispiel wird ein chiRouter:

verwendet

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

Diese Middleware extrahiert die Version, liest die entsprechende overview.md-Datei (passen Sie den Pfad nach Bedarf an), legt die Beschreibung in der Huma-Konfiguration fest und registriert dann die entsprechenden Handler für diese Version. Die Fehlerbehandlung wurde verbessert, um informativere Antworten bereitzustellen. Beachten Sie die explizite Behandlung von Version 3 und einen Standardfall für nicht unterstützte Versionen. Denken Sie daran, Platzhalter wie v1handlers, v2handlers, v3handlers und helpers.Contains durch Ihre tatsächlichen Implementierungen zu ersetzen. Die Funktion helpers.Contains sollte prüfen, ob in einem String-Segment eine Zeichenfolge vorhanden ist.

Dieses Setup stellt sicher, dass die richtige Dokumentation basierend auf der angeforderten API-Version bereitgestellt wird. Denken Sie daran, die docs/v{version}/overview.md-Dateien für jede Version zu erstellen.

Das obige ist der detaillierte Inhalt vonVersionierung in Go Huma. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!