Skip to main content

@ttoss/react-openapi-ui

Render React UI straight from an OpenAPI spec. The spec carries no UI instructions: what each screen shows comes from the operations' schemas, and which screen an operation backs comes from its HTTP method and path shape.

OpenApiApp turns the whole spec into an admin with no wiring. For screens you lay out yourself, each component takes the operationId of an operation, calls the API and derives what it shows from its schemas:

  • OpenApiTable — a list operation as a table with search, status filters, sorting and pagination.
  • OpenApiDetail — a GET of one record as a labelled, formatted read-only view.
  • OpenApiForm — any operation with a request body as a form, with validation; PUT/PATCH pre-fill from the GET on the same path.
  • OpenApiDeleteButton — a DELETE behind a confirmation dialog.

Composed by hand, they make a full admin for a resource; the app only wires navigation between them. useOperationQuery and useOperationMutation expose the same calls for custom UI.

Installation​

pnpm add @ttoss/react-openapi-ui @ttoss/react-i18n

Usage​

import '@ttoss/react-openapi-ui/styles.css';

import {
createFetcher,
OpenApiProvider,
OpenApiTable,
} from '@ttoss/react-openapi-ui';

const fetcher = createFetcher({
baseUrl: 'https://api.example.com',
headers: () => ({ Authorization: `Bearer ${getToken()}` }),
});

export const App = () => {
return (
<OpenApiProvider specUrl="/api/v1/openapi.json" fetcher={fetcher}>
<OpenApiTable operationId="listClients" />
</OpenApiProvider>
);
};

OpenApiProvider takes the spec inline (spec) or fetches it (specUrl). Every request goes through fetcher, so base URL, auth and error handling stay in the app; createFetcher covers the common fetch case.

A full admin from the spec​

<OpenApiProvider specUrl="/api/v1/openapi.json" fetcher={fetcher}>
<OpenApiApp pathPrefix="/api/v1" />
</OpenApiProvider>

OpenApiApp shows a menu with one entry per resource and the screen for the current location. parseResources reads the resources: operations are grouped by tag (untagged ones by their first path segment after api/v1; a tag holding several collections, like /datasets and /evals, becomes one resource per collection), and each takes a role by convention. Parameters declared by $ref are resolved.

OperationScreen
GET /clientsTable; a row opens the record
POST /clientsCreate form ("New"), then the created record
GET /clients/{client_id}Record view
PATCH (preferred) or PUT /clients/{client_id}Edit form ("Edit")
DELETE /clients/{client_id}Delete button with confirmation
Any other write, e.g. POST /clients/{client_id}/send-emailAction form, on the record or on the list

A field with x-ref (or x-soat-ref) holds the id of another resource's record ({ type: 'string', 'x-ref': 'clients' }, matched by path segment, key or tag): forms render it as a select of that resource's records, and tables and record views link to it. On an array of ids (the extension on the array or on its items), forms render checkboxes and tables a list of links.

The location ({ resource: 'clients', view: 'detail', id: 'c1' }) is kept by the component, or by your router when you pass location and onNavigate. formatLocation and parseLocation convert it to and from a path (/clients/c1), and getHref makes navigation render real links:

const location = parseLocation(pathname.replace('/admin', '')) ?? {
resource: 'clients',
view: 'list',
};

<OpenApiApp
location={location}
onNavigate={(next) => navigate(`/admin${formatLocation(next)}`)}
getHref={(next) => `/admin${formatLocation(next)}`}
params={{ project_id: projectId }}
/>;

params reach every request that declares them, in the path or the query (/projects/{project_id}/notes, ?project_id=). A resource nested under a parent (/agents/{agent_id}/versions) is left out of the menu until params holds the parent id. OpenApiView renders only the screen, for apps with their own menu, and useResources exposes the parsed resources. Reads below the record (GET /clients/{client_id}/orders) are not shown yet.

What the table derives from the spec​

From the specBecomes
Response schema (array, or a wrapper like { data: [...], total }, $ref/allOf resolved)Columns, in declaration order, scalars first, up to maxColumns (6)
format: date / date-time, number, booleanLocale-formatted dates and numbers, Yes/No
status/state field with an enumTonal badges and filter chips
Field named like secret, token, api_key, or x-sensitive: trueHidden from derived columns and masked in cells
limit + offset, page + size, or limit + cursor query paramsServer-side pagination (a cursor list follows next_cursor); otherwise paginates in the browser
q / search / query query paramServer-side search (debounced); otherwise filters loaded rows
status query paramServer-side status filter

Sorting by column header is available when the table paginates in the browser.

Customizing columns​

<OpenApiTable
operationId="listClients"
columns={[
'name', // default header and formatting
'status',
{ key: 'balance', header: 'Balance (BRL)' },
{ key: 'address', header: 'City', render: ({ value }) => value?.city },
]}
onRowClick={(client) => navigate(`/clients/${client.id}`)}
actions={<Button>New client</Button>}
/>

Detail​

<OpenApiDetail
operationId="getClient"
params={{ client_id: id }}
actions={({ record }) => (
<OpenApiDeleteButton
operationId="deleteClient"
params={{ client_id: id }}
recordName={String(record.name)}
onSuccess={() => navigate('/clients')}
/>
)}
/>

Fields follow the response schema (writeOnly ones are skipped). Lists of scalars render as badges, flat objects as key/value pairs, nested objects as JSON, and sensitive fields are masked behind a "Show" toggle. fields chooses, orders, relabels or custom-renders them.

Forms​

<OpenApiForm operationId="createClient" onSuccess={(client) => navigate(`/clients/${client.id}`)} />
<OpenApiForm operationId="updateClient" params={{ client_id: id }} onCancel={goBack} />
Field schemaControl
string (format: email, uri, password, date, date-time)Text input of the matching type
string with maxLength > 255, a name like description/notes, or x-widget: textareaTextarea
x-ref / x-soat-ref naming another resourceSelect of that resource's records
array of ids with x-ref / x-soat-refCheckbox group of that resource's records
integer / numberNumber input
booleanCheckbox
enumSelect
array of enumCheckbox group
format: binaryFile input (the body is sent as multipart/form-data)
object / other arrayJSON textarea

readOnly fields are left out. Validation follows required, minimum/maximum, minLength/maxLength and pattern; field errors the API returns as { errors: [{ field, message }] } or { errors: { field: message } } are shown on the field. A PATCH sends only the fields that changed. fields chooses, orders and relabels fields, and render replaces a control.

Styling​

Components are styled with Tailwind; styles.css ships the compiled utilities. Utilities are prefixed (oa:), preflight is not included, and they are emitted outside cascade layers, so the stylesheet neither restyles the host app nor loses to its CSS reset. Theme the components by setting these custom properties on :root or any ancestor:

--openapi-background, --openapi-foreground, --openapi-muted, --openapi-muted-foreground, --openapi-accent, --openapi-border, --openapi-input, --openapi-ring, --openapi-primary, --openapi-primary-foreground, --openapi-destructive.

Without React​

@ttoss/react-openapi-ui/core exports the spec logic (parseResources, findOperation, buildOperationUrl, resolveSchema, getListItemSchema, deriveColumns, formatLocation, …) for use outside React.

See the Storybook stories under React OpenAPI.