Documentation
¶
Overview ¶
Package sdkdocs serves a public SDK documentation site for a GoFastr app — install guides, a live per-entity API reference, auth and error guides — plus download routes for the pregenerated SDK artifacts that `gofastr generate sdk` emits (see framework/sdk for the shared contract).
The reference pages render from the live entity registry on every request, so they cannot drift from the running API. Only the downloadable artifacts can go stale; the manifest's schema hash is compared against the live registry once and a banner + one WARN surface the mismatch.
It is deliberately NOT part of framework/uihost: the screens compose framework/ui, and uihost must never import framework/ui (its LoadAlways styles would leak into every host's CSS bundle). Hosts wire it beside the UI host instead:
coreApp := app.NewApp("My App")
// … screens, uihost.New, fwApp.Mount(host) …
sdkdocs.Mount(coreApp, fwApp.Router(), sdkdocs.Config{
Registry: fwApp.Registry,
Artifacts: os.DirFS("gen/sdk/dist"),
})
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Config ¶
type Config struct {
// BasePath mounts the site (default "/docs/api"). Artifact downloads
// live under BasePath+"/sdk/".
BasePath string
// Registry is the live entity registry (pass fwApp.Registry).
// Required — reference pages render from it per request.
Registry entity.Registry
// Artifacts holds the pregenerated dist directory from
// `gofastr generate sdk` (os.DirFS("gen/sdk/dist") or an embed.FS
// subtree). Nil mounts the docs site without downloads; pages show
// how to generate them instead.
Artifacts fs.FS
// AppName labels the site; defaults to the core-ui app's name.
AppName string
// BaseURL is the public origin baked into install/usage snippets
// (e.g. "https://api.example.com"). Empty renders an honest
// placeholder.
BaseURL string
// APIPrefix mirrors framework.AppConfig.APIPrefix ("" or "api") so
// documented paths match the live mount.
APIPrefix string
// SnakeCase mirrors a server configured with crud.CaseSnake: example
// payload keys render snake_case instead of the camelCase default.
SnakeCase bool
// Entities is an explicit allow-list of entity names (or tables) to
// document. Nil documents Public entities only; IncludeGated
// documents everything registered. Entities outside the included set
// 404 on their reference URL and never appear in the nav — the site
// must not leak the existence of gated schema.
Entities []string
IncludeGated bool
// AuthBasePath is where battery/auth is mounted (default "/auth").
AuthBasePath string
// HasAPITokens enables the token-minting walkthrough (the app wires
// auth.TokensPlugin + TokenMiddleware).
HasAPITokens bool
// Policy, when set, gates every docs screen AND artifact download —
// for internal/partner deployments. Nil = public site.
Policy app.Policy
}
Config configures the SDK docs site.
Source Files