Sign in

Patterns

API reference

Renders an OpenAPI document as a browsable API reference in Halo's own style — our friendly answer to Redoc or Stoplight. Operations group by tag, each with its method badge, parameters, request body, and responses; schemas resolve against components.schemas. You hand it an already-parsed spec object, so it works the same whether the spec comes from a build-time import or a federated bundle.

Live demo

Here's identity's OpenAPI spec, live — the verify side (OpenID Provider discovery and JWKS) plus the health probes, grouped by tag.

Identity API

v0.1.0

Halo’s sovereign identity workload — the source of truth for who, and the issuer of the platform’s stateless JWTs. The current surface is the verify side: OpenID-Provider discovery and JWKS, plus liveness and readiness.

Servershttp://localhost:8082 — Local development server

Health

Liveness and readiness probes for infrastructure health checks.

GET/livez

Liveness probe

Reports process liveness — the server is up and routing.

Responses
200The process is live.
No response body.
GET/readyz

Readiness probe

Reports readiness to serve. Equals liveness until persistence lands.

Responses
200The service is ready to serve traffic.
No response body.

OpenID Provider

OpenID-Provider metadata and signing keys. Every workload validates identity’s JWTs locally against the JWKS published here.

GET/.well-known/openid-configuration

OpenID Provider discovery document

Advertises the issuer and the JWKS location so a workload can self-configure its local token validator from one URL.

Responses
200The discovery document.
OpenIDConfiguration
issuerstring<uri>required
The iss claim; validators pin against it.
jwks_uristring<uri>required
Where the public signing keys are published.
id_token_signing_alg_values_supportedstring[]required
response_types_supportedstring[]
subject_types_supportedstring[]
GET/.well-known/jwks.json

JSON Web Key Set

The public signing keys validators trust. Only the public half of the key is exposed.

Responses
200The active key set.
JWKS
keysJWK[]required

How it's built

native
No third-party viewer. Operations, parameters, and schemas render with the same ui components as everything else — Badge for methods and status, Heading and Text for structure. Your API reference looks like the rest of the app — flat surfaces, solid color fills — not an embedded frame with someone else's styling.
parser-free
Takes an already-parsed spec object; parsing (YAML or JSON → object) is the consumer’s job. The component carries no parser dependency and renders the same from a build-time import or a federated bundle.
federation-fed
The runbook hosts the platform’s API references by feeding each workload’s federated spec here — one doc surface for every workload, no per-workload renderer.

Props

spec: OpenAPISpec
A parsed OpenAPI 3.x document. Required.
className?: string
Optional class on the root element.

Usage

Parse the spec to an object, then pass it. In the runbook, the loader parses each federated openapi.yaml and renders it on the workload’s API-reference route.

tsx
import { ApiReference, type OpenAPISpec } from '@halo-compliance/ui'
import yaml from 'js-yaml'

const spec = yaml.load(rawOpenApiYaml) as OpenAPISpec

<ApiReference spec={spec} />