danielgtaylor / danielgtaylor/huma

Update pinned @scalar/api-reference (1.44.20 → 1.65.1) and/or make the docs asset version configurable

Open
#1,103 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
4.4k
Forks
285
Avg merge
40m
Merged PRs (30d)
1

Description

### 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 `` 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

1. Bump the pinned version to `1.65.1` (SRI for that file: `sha384-G6dkutu2k5IYVyNESLoFIpgaHx38IJTZ/HhrwN0fecTle9te75y8Kru3rJEJ0ZJV`).
2. 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.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start in api.go at DocsRendererScalar and inspect the three pinned Scalar asset references, then trace how Config and DocsRendererConfig are documented and used. Confirm the accepted scope for the version bump versus configurability; done means the selected asset version or override is applied consistently to both the script tag and CSP entry, with its integrity hash.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
api, documentation
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.