Problem
DocsRendererScalar pins @scalar/api-reference@1.44.20, hardcoded in three places in api.go (as of v2.39.0/v2.39.1): the script-src entry of the docs CSP, the <script src=...> tag, and its integrity hash. There is no configuration knob for it, so an application cannot move to a newer Scalar without abandoning huma's docs renderer entirely.
The current Scalar release is 1.65.1. The gap matters in practice — for example, newer versions add a Form | Raw toggle for JSON request bodies (RequestBodyViewToggle), which renders one input per schema property instead of a raw JSON editor. That component does not exist in 1.44.20; I verified by diffing the two standalone bundles:
| symbol |
1.44.20 |
1.65.1 |
RequestBodyViewToggle |
0 |
1 |
` Form ` button |
0 |
1 |
"Fix the body to switch to the form view" |
0 |
1 |
To get it, we had to set humaConfig.DocsPath = "" and serve our own Scalar page (writing the HTML, the CSP and the SRI hash ourselves) while keeping huma for OpenAPIPath and everything else. That works, but it means reimplementing something huma already does well, purely to change one version string.
Proposed change
- Bump the pinned version to
1.65.1 (SRI for that file: sha384-G6dkutu2k5IYVyNESLoFIpgaHx38IJTZ/HhrwN0fecTle9te75y8Kru3rJEJ0ZJV).
- Optionally, make it overridable so applications are not blocked until the next huma release — e.g. a
DocsScriptURL + DocsScriptIntegrity pair on Config, defaulting to the pinned values and flowing into both the <script> tag and the CSP script-src entry. The same would help for the SwaggerUI and Stoplight renderers, which pin their assets the same way.
I am happy to send a PR for either or both, if you tell me which shape you would accept.
Aside, in case it is useful
While looking into this I found that DocsRendererConfig cannot be used to configure Scalar's multi-document mode. Scalar's HTML integration parses data-configuration through a schema (title, slug, url, content, spec, authentication, servers, theme, …) that has no sources key, so a sources array passed through DocsRendererConfig is silently stripped before Scalar's multi-document expander sees it; sources only works through the JS API (Scalar.createApiReference(el, config)). authentication does survive, so OAuth flow extensions passed that way work fine. That is a Scalar-side constraint rather than a huma bug, but it might be worth a sentence in the DocsRendererConfig doc comment so others do not spend time on it.
Problem
DocsRendererScalarpins@scalar/api-reference@1.44.20, hardcoded in three places inapi.go(as of v2.39.0/v2.39.1): thescript-srcentry of the docs CSP, the<script src=...>tag, and itsintegrityhash. There is no configuration knob for it, so an application cannot move to a newer Scalar without abandoning huma's docs renderer entirely.The current Scalar release is
1.65.1. The gap matters in practice — for example, newer versions add aForm | Rawtoggle for JSON request bodies (RequestBodyViewToggle), which renders one input per schema property instead of a raw JSON editor. That component does not exist in1.44.20; I verified by diffing the two standalone bundles:1.44.201.65.1RequestBodyViewToggle` Form `button"Fix the body to switch to the form view"To get it, we had to set
humaConfig.DocsPath = ""and serve our own Scalar page (writing the HTML, the CSP and the SRI hash ourselves) while keeping huma forOpenAPIPathand everything else. That works, but it means reimplementing something huma already does well, purely to change one version string.Proposed change
1.65.1(SRI for that file:sha384-G6dkutu2k5IYVyNESLoFIpgaHx38IJTZ/HhrwN0fecTle9te75y8Kru3rJEJ0ZJV).DocsScriptURL+DocsScriptIntegritypair onConfig, defaulting to the pinned values and flowing into both the<script>tag and the CSPscript-srcentry. The same would help for the SwaggerUI and Stoplight renderers, which pin their assets the same way.I am happy to send a PR for either or both, if you tell me which shape you would accept.
Aside, in case it is useful
While looking into this I found that
DocsRendererConfigcannot be used to configure Scalar's multi-document mode. Scalar's HTML integration parsesdata-configurationthrough a schema (title,slug,url,content,spec,authentication,servers,theme, …) that has nosourceskey, so asourcesarray passed throughDocsRendererConfigis silently stripped before Scalar's multi-document expander sees it;sourcesonly works through the JS API (Scalar.createApiReference(el, config)).authenticationdoes survive, so OAuth flow extensions passed that way work fine. That is a Scalar-side constraint rather than a huma bug, but it might be worth a sentence in theDocsRendererConfigdoc comment so others do not spend time on it.