[costela]

This allows exposing the spec and docs on a separate adapter, potentially under a separate path and/or middleware stacks.

E.g.: (assuming internalRouter and mainRouter are two chi.Router)

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)

This is a bit of a WIP:

• I'm not 100% sure the removal of getAPIPrefix call in the stoplight template is really as harmless as I think
• the other remaining getAPIPrefix call will currently break the schema links if the API is mounted somewhere other than the root.

But regardless of the limitations above: WDYT about the general idea?

[codecov]

Codecov Report

❌ Patch coverage is 96.66667% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 94.71%. Comparing base (606bcc2) to head (d89c772).

Files with missing lines	Patch %	Lines
transforms.go	83.33%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #775      +/-   ##
==========================================
- Coverage   94.72%   94.71%   -0.02%     
==========================================
  Files          25       25              
  Lines        5193     5202       +9     
==========================================
+ Hits         4919     4927       +8     
- Misses        269      270       +1     
  Partials        5        5              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[costela]

Actually, now that I look at the code, it looks like NewSchemaLinkTransformer's prefix parameter isn't even being used? 🙈

I've pushed a second take at this. The new one uses the first parameter to NewSchemaLinkTransformer, so it may be considered a breaking change?
Also I've tried to keep respecting the prefix detection via the OpenAPI.Servers, though I cannot find any place in the documentation where that's actually recommended? Maybe we can skip this backward compatibility and document explicitly how to mount stuff below the root path? There's a commented block in TestChiRouterPrefix that shows the two possible variants.

[robtme]

Hey @costela! Thanks for this contribution, and sorry that it hasn't been reviewed yet! I'm still working on getting up-to-speed with some of the more complex parts of the codebase, but want to try and resolve issues and merge PRs where feasible to do so.

This PR may require @danielgtaylor's review, but in the meantime I'd appreciate it if you could resolve any merge conflicts :)

[Copilot]

🟡 Changes recommended

Documentation and schema URL handling can produce broken links or ignore explicit mount prefixes, while the hook-loop change can panic on shortened slices and skip newly appended hooks.

4 open issues

• Preserve hook iteration safety when CreateHooks changes · New
• Keep nested schema references relative to mounted endpoint · New
• Resolve OpenAPI URL relative to nested docs path · New
• Honor explicit schema mount prefix over API server path · New

What changed in this PR

This PR adds an optional documentation adapter, allowing OpenAPI specifications, documentation, and schemas to use a separate router, mount path, or middleware stack from API endpoints.

Changes:

• Routes documentation-related endpoints through DocsAdapter when configured.
• Extracts a reusable schema-link hook and adds schema mount-prefix handling.
• Adds tests for documentation and specification routing on a separate adapter.

File	Description
transforms.go	Adds a schema-path prefix fallback to link generation.
defaults.go	Exports the schema reference prefix and extracts DefaultSchemaLinkHook.
api.go	Adds documentation adapter routing and adjusts spec URLs and hook iteration.
api_test.go	Tests separate-adapter routing and generated documentation links.
adapters/​humachi/​humachi_test.go	Adds a commented-out schema-link hook example; no test behavior changes.

_{Review effort: Balanced}