Go Huma でのバージョニング

このガイドでは、Go Huma API でのバージョン管理されたドキュメントの実装について詳しく説明します。 API バージョンごとに個別のドキュメントを作成します (例: /v1/docs、/v2/docs)。

中心的なアプローチには、ドキュメント パスを構成し、ミドルウェアを使用してバージョン固有のドキュメント コンテンツを動的にロードすることが含まれます。

構成:

Huma 設定の DocsPath は、ドキュメントの URL 構造を決定します。 バージョンプレフィックスに対応するために、/{version}/docs に設定します:

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

バージョン処理用ミドルウェア:

ミドルウェアはリクエストをインターセプトして URL パスから API バージョンを特定し、対応するドキュメントをロードします。 この例では、chi ルーターを使用します:

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

このミドルウェアはバージョンを抽出し、対応する overview.md ファイルを読み取り (必要に応じてパスを調整)、Huma 構成に説明を設定して、そのバージョンに適切なハンドラーを登録します。 エラー処理が改善され、より有益な応答が提供されるようになりました。 バージョン 3 の明示的な処理と、サポートされていないバージョンのデフォルトのケースに注意してください。 v1handlers、v2handlers、v3handlers、helpers.Contains などのプレースホルダーを実際の実装に置き換えてください。 helpers.Contains 関数は、文字列のスライスに文字列が存在するかどうかをチェックする必要があります。

この設定により、要求された API バージョンに基づいて正しいドキュメントが提供されるようになります。 バージョンごとに docs/v{version}/overview.md ファイルを作成することを忘れないでください。

以上がGo Huma でのバージョニングの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。