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!