feat: support customizing the docs renderer config (#1024)

johnletey · web-flow · commit ffc1eb50fc02 · 2026-05-28T16:59:28.000+01:00
* feat: support customizing the Scalar docs renderer config

* feat: support customizing the SwaggerUI docs renderer config

* docs: demonstrate DocsRendererConfig usage

* docs: dedupe custom renderer guidance
diff --git a/api.go b/api.go
@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"html"
 	"io"
 	"mime/multipart"
 	"net/http"
@@ -205,6 +206,20 @@ type Config struct {
 	// route altogether.
 	DocsRenderer string
 
+	// DocsRendererConfig is an optional renderer-specific config. When set, it is
+	// JSON-marshaled into the docs HTML. Scalar and SwaggerUI use it, Stoplight
+	// Elements ignores it.
+	//
+	// Scalar reads it from the `data-configuration` attribute. See
+	// https://github.com/scalar/scalar/blob/main/documentation/configuration.md
+	// for the options.
+	//
+	// SwaggerUI merges its fields into the SwaggerUIBundle config object. See
+	// https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
+	// for the options. Huma owns the `url` and `dom_id` fields, so setting
+	// them here does nothing.
+	DocsRendererConfig any
+
 	// SchemasPath is the path to the API schemas. If set to `/schemas` it will
 	// allow clients to get `/schemas/{schema}` to view the schema in a browser
 	// or for use in editors like VSCode to provide autocomplete & validation.
@@ -640,6 +655,15 @@ func (a *api) registerDocsRoute() {
 			"style-src 'unsafe-inline'", // TODO: Somehow drop 'unsafe-inline'
 		}
 
+		var configAttr string
+		if a.config.DocsRendererConfig != nil {
+			b, err := json.Marshal(a.config.DocsRendererConfig)
+			if err != nil {
+				panic("failed to marshal DocsRendererConfig: " + err.Error())
+			}
+			configAttr = ` data-configuration="` + html.EscapeString(string(b)) + `"`
+		}
+
 		body = []byte(`<!doctype html>
 <html lang="en">
   <head>
@@ -649,7 +673,7 @@ func (a *api) registerDocsRoute() {
     <title>` + title + `</title>
   </head>
   <body>
-    <script id="api-reference" data-url="` + openAPIPath + `.json"></script>
+    <script id="api-reference" data-url="` + openAPIPath + `.json"` + configAttr + `></script>
     <script src="https://unpkg.com/@scalar/api-reference@1.44.20/dist/browser/standalone.js" crossorigin integrity="sha384-tMz7GAo6dMy55x9tLFtH+sHtogji6Scmb+feBR31TAHmvSPRUTboK9H3M5NFaP4R"></script>
   </body>
 </html>`)
@@ -700,10 +724,19 @@ func (a *api) registerDocsRoute() {
 			"form-action 'none'",
 			"frame-ancestors 'none'",
 			"sandbox allow-same-origin allow-scripts allow-popups allow-popups-to-escape-sandbox",
-			"script-src https://unpkg.com/swagger-ui-dist@5.31.1/swagger-ui-bundle.js 'sha256-loGQL86SKUDRkBgfqt+XGmcml9Plihleifquht4CLYE='",
+			"script-src https://unpkg.com/swagger-ui-dist@5.31.1/swagger-ui-bundle.js 'sha256-gRya58TMnKTH/Tne/zBInjBwFUxL66aMDYvPuAX0lNY='",
 			"style-src https://unpkg.com/swagger-ui-dist@5.31.1/swagger-ui.css",
 		}
 
+		var configAttr string
+		if a.config.DocsRendererConfig != nil {
+			b, err := json.Marshal(a.config.DocsRendererConfig)
+			if err != nil {
+				panic("failed to marshal DocsRendererConfig: " + err.Error())
+			}
+			configAttr = ` data-config="` + html.EscapeString(string(b)) + `"`
+		}
+
 		body = []byte(`<!doctype html>
 <html lang="en">
   <head>
@@ -716,10 +749,13 @@ func (a *api) registerDocsRoute() {
   <body>
     <div id="swagger-ui"></div>
     <script src="https://unpkg.com/swagger-ui-dist@5.31.1/swagger-ui-bundle.js" crossorigin integrity="sha384-o9idN8HE6/V6SAewgnr6/5nz7+Npt5J0Cb4tNyXK8pycsVmgl1ZNbRS7tlEGxd+J"></script>
-    <script data-url="` + openAPIPath + `.json">
-      const url = document.currentScript.dataset.url;
+    <script data-url="` + openAPIPath + `.json"` + configAttr + `>
+      const script = document.currentScript;
+      const url = script.dataset.url;
+      const config = script.dataset.config ? JSON.parse(script.dataset.config) : {};
       window.onload = () => {
         window.ui = SwaggerUIBundle({
+          ...config,
           url: url,
           dom_id: '#swagger-ui',
         });
diff --git a/api_test.go b/api_test.go
@@ -216,6 +216,43 @@ func TestDocsRenderers(t *testing.T) {
 		assert.Contains(t, resp.Body.String(), "@scalar/api-reference")
 	})
 
+	t.Run("ScalarRendererConfig", func(t *testing.T) {
+		_, api := humatest.New(t, huma.Config{
+			OpenAPI: &huma.OpenAPI{
+				Info: &huma.Info{Title: "Test API", Version: "1.0.0"},
+			},
+			DocsPath:     "/docs",
+			DocsRenderer: huma.DocsRendererScalar,
+			DocsRendererConfig: map[string]any{
+				"theme":      "mars",
+				"hideModels": true,
+			},
+			OpenAPIPath: "/openapi",
+			Formats:     huma.DefaultFormats,
+		})
+
+		resp := api.Get("/docs")
+		assert.Equal(t, http.StatusOK, resp.Code)
+		assert.Contains(t, resp.Body.String(), `data-configuration="`)
+		assert.Contains(t, resp.Body.String(), `&#34;theme&#34;:&#34;mars&#34;`)
+		assert.Contains(t, resp.Body.String(), `&#34;hideModels&#34;:true`)
+	})
+
+	t.Run("ScalarRendererConfigInvalid", func(t *testing.T) {
+		assert.Panics(t, func() {
+			humatest.New(t, huma.Config{
+				OpenAPI: &huma.OpenAPI{
+					Info: &huma.Info{Title: "Test API", Version: "1.0.0"},
+				},
+				DocsPath:           "/docs",
+				DocsRenderer:       huma.DocsRendererScalar,
+				DocsRendererConfig: make(chan int),
+				OpenAPIPath:        "/openapi",
+				Formats:            huma.DefaultFormats,
+			})
+		})
+	})
+
 	t.Run("SwaggerUIRenderer", func(t *testing.T) {
 		_, api := humatest.New(t, huma.Config{
 			OpenAPI: &huma.OpenAPI{
@@ -232,6 +269,43 @@ func TestDocsRenderers(t *testing.T) {
 		assert.Contains(t, resp.Body.String(), "swagger-ui-dist")
 	})
 
+	t.Run("SwaggerUIRendererConfig", func(t *testing.T) {
+		_, api := humatest.New(t, huma.Config{
+			OpenAPI: &huma.OpenAPI{
+				Info: &huma.Info{Title: "Test API", Version: "1.0.0"},
+			},
+			DocsPath:     "/docs",
+			DocsRenderer: huma.DocsRendererSwaggerUI,
+			DocsRendererConfig: map[string]any{
+				"defaultModelsExpandDepth": -1,
+				"tryItOutEnabled":          true,
+			},
+			OpenAPIPath: "/openapi",
+			Formats:     huma.DefaultFormats,
+		})
+
+		resp := api.Get("/docs")
+		assert.Equal(t, http.StatusOK, resp.Code)
+		assert.Contains(t, resp.Body.String(), `data-config="`)
+		assert.Contains(t, resp.Body.String(), `&#34;defaultModelsExpandDepth&#34;:-1`)
+		assert.Contains(t, resp.Body.String(), `&#34;tryItOutEnabled&#34;:true`)
+	})
+
+	t.Run("SwaggerUIRendererConfigInvalid", func(t *testing.T) {
+		assert.Panics(t, func() {
+			humatest.New(t, huma.Config{
+				OpenAPI: &huma.OpenAPI{
+					Info: &huma.Info{Title: "Test API", Version: "1.0.0"},
+				},
+				DocsPath:           "/docs",
+				DocsRenderer:       huma.DocsRendererSwaggerUI,
+				DocsRendererConfig: make(chan int),
+				OpenAPIPath:        "/openapi",
+				Formats:            huma.DefaultFormats,
+			})
+		})
+	})
+
 	t.Run("APIPrefix", func(t *testing.T) {
 		_, api := humatest.New(t, huma.Config{
 			OpenAPI: &huma.OpenAPI{
diff --git a/docs/docs/features/api-docs.md b/docs/docs/features/api-docs.md
@@ -18,73 +18,46 @@ You can switch to other documentation renderers using `config.DocsRenderer`. The
 
 !!! info "Disabling the Docs"
 
-    You can disable the built-in documentation by setting `config.DocsPath` to an empty string. This allows you to provide your own documentation renderer if you wish.
+    You can disable the built-in documentation by setting `config.DocsPath` to an empty string, then register your own route on the underlying router. The `DocsRenderer*` functions in [`api.go`](https://github.com/danielgtaylor/huma/blob/main/api.go) show what to return.
 
 !!! warning "Middleware Conflicts"
 
     Some middleware can interfere with the documentation renderer's ability to fetch the OpenAPI spec. For example, [go-chi/chi](https://github.com/go-chi/chi)'s `middleware.URLFormat` will rewrite URLs that end in `.json` or `.yaml` (e.g. `/openapi.json` -> `/openapi`), which can lead to 404 errors for the spec. If you encounter this, consider disabling that middleware or configuring it to skip the OpenAPI and documentation paths.
 
 ## Customizing Documentation
 
-You can customize the generated documentation by providing your own renderer function to the API adapter or by using the underlying router directly.
+Each renderer accepts its own options through `config.DocsRendererConfig`. Set it to any value that marshals to JSON (a `map[string]any` is easiest), and Huma writes it into the docs HTML. Scalar and SwaggerUI support it; Stoplight Elements ignores it.
 
 ### Scalar Docs
 
-[Scalar Docs](https://github.com/scalar/scalar?tab=readme-ov-file#readme) provide a featureful and customizable API documentation experience that feels similar to Postman in your browser.
+[Scalar Docs](https://github.com/scalar/scalar#readme) provide a featureful and customizable API documentation experience that feels similar to Postman in your browser.
 
 ```go title="code.go"
 router := chi.NewRouter()
 config := huma.DefaultConfig("Docs Example", "1.0.0")
-config.DocsPath = ""
+config.DocsRenderer = huma.DocsRendererScalar
 
-api := humachi.New(router, config)
+// Optional. Scalar reads these from the `data-configuration` attribute. See
+// https://github.com/scalar/scalar/blob/main/documentation/configuration.md
+config.DocsRendererConfig = map[string]any{
+	"theme":      "mars", // one of: default, alternate, moon, purple, solarized, ...
+	"hideModels": true,   // hide the models section
+}
 
-router.Get("/docs", func(w http.ResponseWriter, r *http.Request) {
-	// Please also refer to the "DocsRendererScalar" renderer code inside api.go on what to return here
-	csp := []string{
-		"default-src 'none'",
-		"base-uri 'none'",
-		"connect-src 'self'",
-		"form-action 'none'",
-		"frame-ancestors 'none'",
-		"sandbox allow-same-origin allow-scripts",
-		"script-src 'unsafe-eval' https://unpkg.com/@scalar/api-reference@1.44.20/dist/browser/standalone.js", // TODO: Somehow drop 'unsafe-eval'
-		"style-src 'unsafe-inline'", // TODO: Somehow drop 'unsafe-inline'
-	}
-	w.Header().Set("Content-Security-Policy", strings.Join(csp, "; "))
-	w.Header().Set("Content-Type", "text/html")
-	w.Write([]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>API Reference</title>
-  </head>
-  <body>
-    <script id="api-reference" data-url="/openapi.json"></script>
-    <script src="https://unpkg.com/@scalar/api-reference@1.44.20/dist/browser/standalone.js" crossorigin integrity="sha384-tMz7GAo6dMy55x9tLFtH+sHtogji6Scmb+feBR31TAHmvSPRUTboK9H3M5NFaP4R"></script>
-  </body>
-</html>`))
-})
+api := humachi.New(router, config)
 ```
 
 ![Scalar Docs](./scalar.png)
 
 ### Stoplight Elements
 
-You can customize the default docs by providing your own HTML so you can set the layout, styles, colors, etc as needed.
+[Stoplight Elements](https://stoplight.io/open-source/elements) is the default renderer, so you get it without setting `config.DocsRenderer` at all. It doesn't read `config.DocsRendererConfig`.
 
 ```go title="code.go"
 router := chi.NewRouter()
 config := huma.DefaultConfig("Docs Example", "1.0.0")
-config.DocsPath = ""
 
 api := humachi.New(router, config)
-
-router.Get("/docs", func(w http.ResponseWriter, r *http.Request) {
-	// Please refer to the "DocsRendererStoplightElements" renderer code inside api.go on what to return here
-})
 ```
 
 ![Stoplight Elements Stacked](./elements-stacked.png)
@@ -96,13 +69,16 @@ router.Get("/docs", func(w http.ResponseWriter, r *http.Request) {
 ```go title="code.go"
 router := chi.NewRouter()
 config := huma.DefaultConfig("Docs Example", "1.0.0")
-config.DocsPath = ""
+config.DocsRenderer = huma.DocsRendererSwaggerUI
 
-api := humachi.New(router, config)
+// Optional. These fields are merged into the SwaggerUIBundle config object. See
+// https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
+config.DocsRendererConfig = map[string]any{
+	"defaultModelsExpandDepth": -1,   // hide the models section
+	"tryItOutEnabled":          true, // enable "Try it out" by default
+}
 
-router.Get("/docs", func(w http.ResponseWriter, r *http.Request) {
-	// Please refer to the "DocsRendererSwaggerUI" renderer code inside api.go on what to return here
-})
+api := humachi.New(router, config)
 ```
 
 ![SwaggerUI](./swaggerui.png)
