Put docs page behind authentication

[anthansson]

Hey!

Me and my team have put our API behind basic authentication and thus the docs cannot be loaded in a browser.

We ended up hiding the docs endpoint on a cluster internal server but now have to forward-proxy into our deployment in order to visit the docs. We achieved it by passing the openapi spec generated by the human API to this handler:

go

func DocsHandler(openAPI *huma.OpenAPI, externalURL string) http.Handler {
	// Point the servers to the external URL instead of "/"
	// so that we actually can run requests from the UI!
	openAPI.Servers = []*huma.Server{{URL: externalURL}}

	tmpl, err := template.New("docs.html").Parse(templateFile)
	if err != nil {
		slogutil.Fatal("error parsing docs template", slogutil.Error(err))
	}

	router := chi.NewRouter()
	router.Get("/", func(w http.ResponseWriter, r *http.Request) {
		ctx := r.Context()
		prefix := strings.TrimSuffix(r.URL.Path, "/")

		if err := tmpl.Execute(w, struct{ APIDescriptionURL string }{fmt.Sprintf("%s/openapi.yaml", prefix)}); err != nil {
			slog.ErrorContext(ctx, "error executing template", slogutil.Error(err))
			httpsrv.RespondError(ctx, w, err)
			return
		}
	})

	router.Get("/openapi.json", func(w http.ResponseWriter, r *http.Request) {
		jsonBytes, err := json.Marshal(openAPI)
		if err != nil {
			slog.ErrorContext(r.Context(), "error encoding JSON", slogutil.Error(err))
			httpsrv.RespondError(r.Context(), w, err)
			return
		}
		w.Header().Set("Content-Type", "application/vnd.oai.openapi+json")
		w.WriteHeader(http.StatusOK)
		w.Write(jsonBytes)
	})

	router.Get("/openapi.yaml", func(w http.ResponseWriter, r *http.Request) {
		yaml, err := openAPI.YAML()
		if err != nil {
			slog.ErrorContext(r.Context(), "error encoding YAML", slogutil.Error(err))
			httpsrv.RespondError(r.Context(), w, err)
		}
		w.Header().Set("Content-Type", "application/vnd.oai.openapi+yaml")
		w.WriteHeader(http.StatusOK)
		w.Write(yaml)
	})

	return router
}

But optimally we would like to put our docs behind some authentication that can be supplied on the docs page in a browser so that we can share documentation with external people. Any tips?