Scalar API Reference

Regius can serve an interactive API reference UI powered by Scalar from an OpenAPI 3.1 document.

Features

• Opt-in via SCALAR_ENABLED: When enabled, two routes are registered — the docs UI (/docs by default) and the OpenAPI spec endpoint (/openapi.json by default)
• Hybrid spec source: Build the OpenAPI document programmatically with the api.Document builder, or serve a static openapi.yaml/openapi.json file from disk (SCALAR_SPEC_FILE); when both are set, the static file takes precedence
• Configurable CDN: The Scalar JS bundle is loaded from jsDelivr by default; set SCALAR_CDN_URL to a local URL for air-gapped/offline use
• Client library filtering: Control which code example tabs (curl, fetch, axios, etc.) appear via SCALAR_SHOW_CLIENTS
• API response envelope helpers: WriteAPIResponse / WriteAPIError produce a standardized {data, error, meta} JSON envelope
• Pagination helpers: Offset-based (api.ParseOffsetPagination) and cursor-based (api.ParseCursorPagination) with metadata generation
• Scaffolding: regius make api <name> generates a CRUD handler with the response envelope, pagination, and an OpenAPI document builder

Usage

Programmatic Spec

import "github.com/hbarral/regius/api"

doc := api.NewDocument("My API", "1.0.0").
    Description("A sample API").
    Server("https://api.example.com", "Production")

doc.Path("/users/{id}", api.NewPathItem().WithGet(
    api.NewOperation("Users", "Get a user").
        WithOperationID("getUser").
        Param("id", "path", "User ID", true, api.IntSchema()).
        JSONResponse(200, "User found", api.ObjectSchema()).
        PlainResponse(404, "User not found"),
))

a.App.Scalar.Spec = doc

Static Spec

SCALAR_ENABLED=true
SCALAR_SPEC_FILE=./openapi.yaml

API Response Envelope

// Success with pagination
p := api.ParseOffsetPagination(r, 20, 100)
// ... fetch items ...
h.App.WriteAPIResponse(w, http.StatusOK, items, &api.Meta{
    Pagination: p.Meta(total),
})

// Error
h.App.WriteAPIError(w, http.StatusNotFound, "not_found", "user not found")

Client Library Filtering

The Scalar UI generates code examples for many HTTP clients. Use SCALAR_SHOW_CLIENTS to control which are shown. The value is injected as a raw JavaScript expression and converted to Scalar's hiddenClients option at runtime.

Value	Effect
(empty / commented out)	Show all clients (default)
true	Show all clients (explicit)
["fetch","curl"]	Show only the listed clients
{"js":true,"shell":["curl"]}	Per-language: show all JS clients + only curl from shell

Available client names (by language):

Language	Clients
C	libcurl
C#	httpclient, restsharp
Clojure	clj_http
Dart	http
F#	httpclient
Go	native
HTTP	http1.1
Java	asynchttp, nethttp, okhttp, unirest
JavaScript	axios, fetch, jquery, ofetch, xhr
Julia	http
Kotlin	okhttp
Node.js	axios, fetch, ofetch, undici
Objective-C	nsurlsession
OCaml	cohttp
PHP	curl, guzzle, laravel
PowerShell	restmethod, webrequest
Python	aiohttp, httpx_async, httpx_sync, python3, requests
R	httr2
Ruby	native
Rust	reqwest
Shell	curl, httpie, wget
Swift	nsurlsession

Examples:

# Show only curl and fetch
SCALAR_SHOW_CLIENTS=["curl","fetch"]

# Show all JavaScript and Node.js clients, plus curl from shell
SCALAR_SHOW_CLIENTS={"js":true,"node":true,"shell":["curl"]}

Environment Variables

SCALAR_ENABLED=false
#SCALAR_DOCS_PATH=/docs
#SCALAR_SPEC_PATH=/openapi.json
#SCALAR_TITLE=API Reference
#SCALAR_CDN_URL=https://cdn.jsdelivr.net/npm/@scalar/api-reference
#SCALAR_SPEC_FILE=
#SCALAR_THEME=default
#SCALAR_SHOW_CLIENTS={"go":["native"],"java":true,"curl","fetch"}