feat: support docs on separate adapter

costela · costela · commit 236c7ef7b846 · 2025-03-21T23:44:26.000+01:00
This allows exposing the spec and docs on a separate adapter, potentially under a separate path and/or middleware stacks.

E.g.:
```
opts := huma.DefaultConfig("foo", "0.0.1")
	opts.DocsAdapter = humachi.NewAdapter(internalRouter)
	opts.CreateHooks = []func(huma.Config) huma.Config{
		huma.DefaultSchemaLinkHook(huma.DefaultSchemaRefPrefix, internalPrefix), // assuming internalRouter above is mounted under internalPrefix
	}

	adapter := humachi.NewAdapter(mainRouter)
huma.NewAPI(opts, adapter)
```
diff --git a/api.go b/api.go
@@ -10,7 +10,6 @@ import (
 	"mime/multipart"
 	"net/http"
 	"net/url"
-	"path"
 	"reflect"
 	"regexp"
 	"strings"
@@ -181,6 +180,15 @@ type Config struct {
 	// blank and attach it directly to the router or adapter.
 	DocsPath string
 
+	// DocsAdapter is an optional [Adapter] that will be used to serve the API
+	// documentation. If unset, the main adapter will be used.
+	// Setting this allows you to use a different router or middleware stack for
+	// the documentation.
+	// Note that if this [Adapter] has a different path than the main one, the
+	// default CreateHook set in [DefaultConfig] needs to be modified to account
+	// for it.
+	DocsAdapter Adapter
+
 	// 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.
@@ -362,7 +370,7 @@ func getAPIPrefix(oapi *OpenAPI) string {
 //	config := huma.DefaultConfig("Example API", "1.0.0")
 //	api := huma.NewAPI(config, adapter)
 func NewAPI(config Config, a Adapter) API {
-	for i := 0; i < len(config.CreateHooks); i++ {
+	for i := range config.CreateHooks {
 		config = config.CreateHooks[i](config)
 	}
 
@@ -400,9 +408,14 @@ func NewAPI(config Config, a Adapter) API {
 		newAPI.formatKeys = append(newAPI.formatKeys, k)
 	}
 
+	docsAdapter := newAPI.adapter
+	if config.DocsAdapter != nil {
+		docsAdapter = config.DocsAdapter
+	}
+
 	if config.OpenAPIPath != "" {
 		var specJSON []byte
-		a.Handle(&Operation{
+		docsAdapter.Handle(&Operation{
 			Method: http.MethodGet,
 			Path:   config.OpenAPIPath + ".json",
 		}, func(ctx Context) {
@@ -413,7 +426,7 @@ func NewAPI(config Config, a Adapter) API {
 			ctx.BodyWriter().Write(specJSON)
 		})
 		var specJSON30 []byte
-		a.Handle(&Operation{
+		docsAdapter.Handle(&Operation{
 			Method: http.MethodGet,
 			Path:   config.OpenAPIPath + "-3.0.json",
 		}, func(ctx Context) {
@@ -424,7 +437,7 @@ func NewAPI(config Config, a Adapter) API {
 			ctx.BodyWriter().Write(specJSON30)
 		})
 		var specYAML []byte
-		a.Handle(&Operation{
+		docsAdapter.Handle(&Operation{
 			Method: http.MethodGet,
 			Path:   config.OpenAPIPath + ".yaml",
 		}, func(ctx Context) {
@@ -435,7 +448,7 @@ func NewAPI(config Config, a Adapter) API {
 			ctx.BodyWriter().Write(specYAML)
 		})
 		var specYAML30 []byte
-		a.Handle(&Operation{
+		docsAdapter.Handle(&Operation{
 			Method: http.MethodGet,
 			Path:   config.OpenAPIPath + "-3.0.yaml",
 		}, func(ctx Context) {
@@ -448,14 +461,10 @@ func NewAPI(config Config, a Adapter) API {
 	}
 
 	if config.DocsPath != "" {
-		a.Handle(&Operation{
+		docsAdapter.Handle(&Operation{
 			Method: http.MethodGet,
 			Path:   config.DocsPath,
 		}, func(ctx Context) {
-			openAPIPath := config.OpenAPIPath
-			if prefix := getAPIPrefix(newAPI.OpenAPI()); prefix != "" {
-				openAPIPath = path.Join(prefix, openAPIPath)
-			}
 			ctx.SetHeader("Content-Type", "text/html")
 			title := "Elements in HTML"
 			if config.Info != nil && config.Info.Title != "" {
@@ -476,7 +485,7 @@ func NewAPI(config Config, a Adapter) API {
   <body style="height: 100vh;">
 
     <elements-api
-      apiDescriptionUrl="` + openAPIPath + `.yaml"
+      apiDescriptionUrl="` + strings.TrimPrefix(config.OpenAPIPath, "/") + `.yaml"
       router="hash"
       layout="sidebar"
       tryItCredentialsPolicy="same-origin"
@@ -488,7 +497,7 @@ func NewAPI(config Config, a Adapter) API {
 	}
 
 	if config.SchemasPath != "" {
-		a.Handle(&Operation{
+		docsAdapter.Handle(&Operation{
 			Method: http.MethodGet,
 			Path:   config.SchemasPath + "/{schema}",
 		}, func(ctx Context) {
diff --git a/defaults.go b/defaults.go
@@ -3,8 +3,12 @@ package huma
 import (
 	"encoding/json"
 	"io"
+	"path"
 )
 
+// DefaultSchemaNamer is the default prefix used to reference schemas in the API spec.
+const DefaultSchemaRefPrefix = "#/components/schemas/"
+
 // DefaultJSONFormat is the default JSON formatter that can be set in the API's
 // `Config.Formats` map. This is used by the `DefaultConfig` function.
 //
@@ -53,10 +57,7 @@ var DefaultFormats = map[string]Format{
 //
 //	import _ "github.com/danielgtaylor/huma/v2/formats/cbor"
 func DefaultConfig(title, version string) Config {
-	schemaPrefix := "#/components/schemas/"
-	schemasPath := "/schemas"
-
-	registry := NewMapRegistry(schemaPrefix, DefaultSchemaNamer)
+	registry := NewMapRegistry(DefaultSchemaRefPrefix, DefaultSchemaNamer)
 
 	return Config{
 		OpenAPI: &OpenAPI{
@@ -71,20 +72,24 @@ func DefaultConfig(title, version string) Config {
 		},
 		OpenAPIPath:   "/openapi",
 		DocsPath:      "/docs",
-		SchemasPath:   schemasPath,
+		SchemasPath:   "/schemas",
 		Formats:       DefaultFormats,
 		DefaultFormat: "application/json",
 		CreateHooks: []func(Config) Config{
-			func(c Config) Config {
-				// Add a link transformer to the API. This adds `Link` headers and
-				// puts `$schema` fields in the response body which point to the JSON
-				// Schema that describes the response structure.
-				// This is a create hook so we get the latest schema path setting.
-				linkTransformer := NewSchemaLinkTransformer(schemaPrefix, c.SchemasPath)
-				c.OpenAPI.OnAddOperation = append(c.OpenAPI.OnAddOperation, linkTransformer.OnAddOperation)
-				c.Transformers = append(c.Transformers, linkTransformer.Transform)
-				return c
-			},
+			DefaultSchemaLinkHook(DefaultSchemaRefPrefix, ""),
 		},
 	}
 }
+
+// DefaultSchemaLinkHook adds a link transformer to the API.
+// This adds `Link` headers and puts `$schema` fields in the response body which
+// point to the JSON Schema that describes the response structure.
+// This is a create hook so we get the latest schema path setting.
+func DefaultSchemaLinkHook(schemaRefPrefix, schemaPathPrefix string) func(c Config) Config {
+	return func(c Config) Config {
+		linkTransformer := NewSchemaLinkTransformer(schemaRefPrefix, path.Join(schemaPathPrefix, c.SchemasPath))
+		c.OpenAPI.OnAddOperation = append(c.OpenAPI.OnAddOperation, linkTransformer.OnAddOperation)
+		c.Transformers = append(c.Transformers, linkTransformer.Transform)
+		return c
+	}
+}
