Versi dalam Go Huma

Panduan ini memperincikan pelaksanaan dokumentasi versi dalam API Go Huma. Kami akan membuat dokumentasi berasingan untuk setiap versi API (cth., /v1/docs, /v2/docs).

Pendekatan teras melibatkan konfigurasi laluan dokumentasi dan menggunakan perisian tengah untuk memuatkan kandungan dokumentasi khusus versi secara dinamik.

Tatarajah:

DocsPath dalam konfigurasi Huma menentukan struktur URL dokumentasi. Kami menetapkannya kepada /{version}/docs untuk menampung awalan versi:

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

Perisian Tengah untuk Pengendalian Versi:

Perisian tengah memintas permintaan untuk menentukan versi API daripada laluan URL dan memuatkan dokumentasi yang sepadan. Contoh ini menggunakan penghala 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)

Perisian tengah ini mengekstrak versi, membaca fail overview.md yang sepadan (laraskan laluan mengikut keperluan), menetapkan penerangan dalam konfigurasi Huma, dan kemudian mendaftarkan pengendali yang sesuai untuk versi itu. Pengendalian ralat dipertingkatkan untuk memberikan respons yang lebih bermaklumat. Perhatikan pengendalian eksplisit versi 3 dan kes lalai untuk versi yang tidak disokong. Ingat untuk menggantikan ruang letak seperti v1handlers, v2handlers, v3handlers dan helpers.Contains dengan pelaksanaan sebenar anda. Fungsi helpers.Contains harus menyemak sama ada rentetan wujud dalam kepingan rentetan.

Persediaan ini memastikan bahawa dokumentasi yang betul disampaikan berdasarkan versi API yang diminta. Ingat untuk mencipta docs/v{version}/overview.md fail untuk setiap versi.

Atas ialah kandungan terperinci Versi dalam Go Huma. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!