Go Huma의 버전 관리

이 가이드에서는 Go Huma API에서 버전이 지정된 문서를 구현하는 방법을 자세히 설명합니다. 각 API 버전(예: /v1/docs, /v2/docs)에 대해 별도의 문서를 만들 예정입니다.

핵심 접근 방식은 문서 경로를 구성하고 미들웨어를 사용하여 버전별 문서 콘텐츠를 동적으로 로드하는 것입니다.

구성:

Huma 구성의 DocsPath는 문서 URL 구조를 나타냅니다. 버전 접두어를 수용하기 위해 /{version}/docs로 설정했습니다.

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

버전 처리를 위한 미들웨어:

미들웨어는 URL 경로에서 API 버전을 확인하기 위한 요청을 가로채고 해당 문서를 로드합니다. 이 예에서는 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)

이 미들웨어는 버전을 추출하고 해당 overview.md 파일을 읽고(필요에 따라 경로 조정) Huma 구성에 설명을 설정한 다음 해당 버전에 적합한 핸들러를 등록합니다. 보다 유익한 응답을 제공하기 위해 오류 처리가 개선되었습니다. 버전 3의 명시적 처리와 지원되지 않는 버전의 기본 사례에 유의하세요. v1handlers, v2handlers, v3handlers, helpers.Contains 같은 자리 표시자를 실제 구현으로 바꾸는 것을 잊지 마세요. helpers.Contains 함수는 문자열 조각에 문자열이 존재하는지 확인해야 합니다.

이 설정을 통해 요청된 API 버전에 따라 올바른 문서가 제공됩니다. 각 버전에 대한 docs/v{version}/overview.md 파일을 생성하는 것을 잊지 마세요.

위 내용은 Go Huma의 버전 관리의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!