Offline API Docs
#1035
|
What is the simplest way to bundle the API documentation UI (e.g. Stoplight Elements) in the built huma application binary, or at least make it easy to serve the docs UI offline? A quick look at the code shows that the builtin API docs use hardcoded CDN URLs. |
Answered by
wolveix
May 30, 2026
Replies: 1 comment 1 reply
|
Hi @akhayyat. The simplest way to do this would be to disable the built-in docs renderers and set your own route, e.g.: config := huma.DefaultConfig("Your App", version)
config.DocsPath = ""
router = humachi.New(mux, config)
router.Adapter().Handle(&huma.Operation{
Method: http.MethodGet,
Path: server.apiPath + "/docs",
}, func(ctx huma.Context) {
ctx.SetHeader("Content-Type", "text/html")
if _, err := ctx.BodyWriter().Write([]byte(`<!doctype html><html lang="en"><head><title>Your App - API Reference</title><meta charset="utf-8"><meta content="width=device-width,initial-scale=1" name="viewport"></head><body><script data-url="` + server.apiPath + `/docs.json" id="api-reference"></script><script>let apiReference = document.getElementById("api-reference")</script><script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script></body></html>`)); err != nil {
server.logger.Error().Err(err).Msg("an error occurred while serving the API documentation")
}
})Then just swap out the CDN references with bundled assets, using Go's built-in embed functionality. |
1 reply
|
Thank y0u for the confirmation. I came up with the following based on these suggestions and the built-in implementation, and it works rather nicely; so I'm leaving a copy here for the benefit of others: //go:embed stoplight-elements/styles.min.css
var uiCSS string
//go:embed stoplight-elements/web-components.min.js
var uiJS string
// Serve the API docs UI (e.g. Stoplight Elements) offline
func RegisterDocsRoute(api huma.API) {
title := "My API Documentation"
csp := []string{
"default-src 'none'",
"base-uri 'none'",
"connect-src 'self'",
"form-action 'none'",
"frame-ancestors 'none'",
"sandbox allow-same-origin allow-scripts allow-popups allow-popups-to-escape-sandbox",
"script-src 'unsafe-inline'",
"style-src 'unsafe-inline'",
}
body := []byte(`<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="referrer" content="no-referrer">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>` + title + `</title>
<style>` + uiCSS + `</style>
<script>` + uiJS + `</script>
</head>
<body style="height: 100vh;">
<elements-api
apiDescriptionUrl="` + "/openapi" + `.yaml"
router="hash"
layout="sidebar"
tryItCredentialsPolicy="same-origin"
></elements-api>
</body>
</html>`)
api.Adapter().Handle(&huma.Operation{
Method: http.MethodGet,
Path: "/docs",
}, func(ctx huma.Context) {
ctx.SetHeader("Content-Security-Policy", strings.Join(csp, "; "))
ctx.SetHeader("Content-Type", "text/html")
ctx.BodyWriter().Write(body)
})
} |
Answer selected by
wolveix
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Hi @akhayyat. The simplest way to do this would be to disable the built-in docs renderers and set your own route, e.g.: