Skip to content

Spec Extensions

react-openapi is configured entirely by x- extensions inside the OpenAPI document. This page is the catalogue; the repository README.md carries the complete authoring guide with a minimal worked spec.

Validation levels — error (the admin will not render), warning (renders, shown in a snackbar), info (informational note).

📦 Schema level

Extension Required Purpose
x-resource ✅ Marks the schema as a resource; value must equal the collection path segment (pets → /pets). Schemas without it are skipped entirely (use for ErrorBody, Metadata, …).
x-primary-key ✅ Property used as the :id path parameter. Must exist in properties.
x-display-format ✅ Template such as "{name} - #{id}"; used for row labels, detail titles and FK options.
x-list-columns ✅ Ordered property names for the datatable; every entry must exist.

📦 Property level

Extension Required Purpose
x-label ✅ Label for form field, table header and detail view.
x-order ✅ Field ordering; ties break alphabetically.
x-description — Helper text / placeholder; falls back to x-label.
x-hidden — { form, list, detail } visibility; missing keys default to false.
x-filterable — Marks the field filterable (UI integration reserved).
x-sortable — Sends ?sort=field / ?sort=-field on the list endpoint.
x-edit-as — e.g. date — edit a date-time field with a date input.
x-fk — { resource, prefetch } — render a dropdown or multi-select for a $ref.
x-ui-type — image — file/image upload control.
x-upload / x-upload-url — Raw-binary upload (type: image\|pdf\|html\|csv\|file) or an image POST endpoint with {id}.

Foreign keys

1
2
3
4
5
owner:
  $ref: '#/components/schemas/Parent'
  x-fk:
    resource: parents   # the target's x-resource value, not the schema name
    prefetch: true      # false -> load options on focus
  • Single $ref → FkSelectField dropdown; type: array → FkMultiSelectField.
  • Options are fetched as GET /{target}?limit=0 (paginated) or GET /{target}, then formatted with the target's x-display-format.
  • Validator rules: resource must match some x-resource, and that target must have x-display-format + x-primary-key.
  • A $ref without x-fk renders read-only (InlineRefField chips, or a disabled JSON text field in forms) and emits an info message.

📦 Path level

Extension Purpose
x-sse Marks a path as a Server-Sent Events stream instead of REST CRUD. 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
/pets/events:
  x-sse: true
  get:
    summary: Subscribe to Pet events
    responses:
      200:
        description: SSE stream of Pet change events
        content:
          text/event-stream:
            schema: { type: object }

An x-sse resource is excluded from the sidebar, list/detail routes and CRUD hooks — it appears only in the streaming collection and is reachable through useResource(name).stream / SseStreamView.

📦 Security / auth

Derived from components.securitySchemes.bearerAuth:

Extension Meaning
x-server-url Auth server base URL → AuthConfig.serverUrl
x-login-path → loginPath
x-register-path → registerPath
x-logout-path → logoutPath
x-me-path → mePath
x-introspect-path → introspectPath

Requests carry Authorization: Bearer <token> from SpecConfiguration.getToken. On a 401 the stored token is cleared so a refresh flow can take over.

📦 Profile (x-profile)

x-profile operations describe the current-user view/edit/create screens. SpecConfiguration.profileComponents supplies React components for them, and they are mounted through the exported ProfileRoutes.

✅ Validator rules (summary)

For each schema with x-resource:

  1. x-primary-key, x-display-format, x-list-columns present and valid.
  2. Every property has x-label and x-order.
  3. $ref without x-fk → info; x-fk target must exist and be displayable.
  4. The x-resource path exists with GET + POST.
  5. The item path /{resource}/{id} exists with GET + PUT + DELETE.
  6. If pagination params exist, limit must carry a schema.default.