Skip to content

Admin UI

Everything on screen comes from the loaded spec. This page lists the pieces you compose with, and the three ways to override the generated behaviour.

📦 Components

Export Purpose
AppProvider Loads and validates the spec, builds resource configs, initialises the axios client, provides context. Wrap the app with it.
Admin Sidebar + nested routes for every resource. Takes basePath.
ProfileRoutes Routes for x-profile view/edit/create operations.
ListCellRenderer One list/table cell; honours FK display formats, inline refs, enums, booleans.
DetailFieldRenderer Read-only label + value pair in the detail view.
FormFieldRenderer Editable form field; dispatches to the concrete control.
FilterBar / SideMenu / Layout Layout primitives used by Admin.
ValidationAlert Spec validation errors/warnings surface.
SseStreamView Live stream card: status, event counter, latest event, snackbar.
SseConnectionStatus Green/red dot with Connected/Disconnected — reactive everywhere.
MultiEnumField, CurrencyField, FkMultiSelectField Exported controls you can reuse in custom screens.

Field renderer dispatch

Condition Form control List / detail
x-fk, not an array FkSelectField display-format cell
x-fk, type: array FkMultiSelectField chips
enum EnumField chip
type: boolean BooleanField (switch) Yes/No chip
type: integer / number NumberField typography
format: date / date-time DateField typography
x-ui-type: image / x-upload upload control avatar / chip
$ref without x-fk disabled JSON field InlineRefField chips
otherwise StringField typography

📦 Hooks

1
2
3
4
const { config, resources, schemas, loading, errors, warnings } = useAppContext();

const { resource, components, list, get, create, update, remove, stream, loading, error } =
  useResource("pets");
  • useAppContext() — the whole derived model.
  • useResource(name) — CRUD + optional stream(handlers, pathParams?) → { close } for x-sse resources; components holds the per-resource filter widgets.
  • useItemSse(url, handlers) — subscribe to one item's event stream.
  • useFkFieldOptions(...) / getApi() — FK options and the configured axios instance for custom calls.
  • sanitizePayload(payload, resolver) — strips/normalises fields before create/update.

📦 Three ways to customise

1. Per-resource behaviour — specConfiguration.resourceConfig

1
2
3
4
5
6
<AppProvider specConfiguration={{
  specUrl: "/api/openapi.yaml",
  resourceConfig: {
    invoices: { filterOptions: { mode: "sidebar" }, fieldTypes: { amount: "currency" } },
  },
}} />

2. Profile screens — specConfiguration.profileComponents

1
2
3
4
<AppProvider specConfiguration={{
  specUrl: "/api/openapi.yaml",
  profileComponents: { view: ProfileView, edit: ProfileEdit, create: ProfileCreate },
}} />

3. Your own screens — hooks

1
2
3
4
5
6
7
8
import { useAppContext, SseStreamView } from "react-openapi";

function MyStreamPage() {
  const { resources } = useAppContext();
  const res = resources.find((r) => r.name === "calls");
  if (!res) return null;
  return <SseStreamView resource={res} />;
}

📡 Streaming

useResource("calls").stream({ onEvent, onError, onOpen }) returns a subscription with close(). Reconnection is browser-native; components read connection state from SseConnectionStatus.

🔐 Auth

getToken is called per request and injected as Authorization: Bearer. Auth endpoints are derived from the spec's securitySchemes.bearerAuth extensions (see Spec Extensions).

Combine with react-auth

react-auth owns the login/register UI and the session; react-openapi only needs a token. Feed getToken: tokenStore.get into specConfiguration to share one session between the two.