<rapi-doc-mini> API Reference
One endpoint or a few, with its Try console, inside a blog post, tutorial or changelog. It ships in the same bundle as <rapi-doc>.
Config Options
HTML Attributes#
Set on the <rapi-doc-mini> element in HTML, or changed at runtime with setAttribute.
Spec & Content Attributes#7
| Attribute Name | Description & Allowed Values | Default |
|---|---|---|
URL of the OpenAPI specification file (JSON or YAML) to load and render. | (empty) | |
Allowed: Sorts endpoints within each tag group by path, HTTP method, or summary. 'none' leaves the sort
order unmodified. ⓘ This is a static initialization attribute. It will not have any effect if modified using JavaScript after the spec is rendered. | path | |
Which operations to show: a space- or comma-separated list of terms. An operation is shown when
it matches any include term (every one is, without one) and no ! term. A term is an operationId (getPetById), a
method and path (GET /pet/{petId}), a path for all its methods,
a path glob (/pet/**; * is one
segment, ** any number), tag:store, badge:Beta (an x-badges label, or an OpenAPI 3.2 tag of kind: badge) or
deprecated; ! before a term
leaves out what it matches (!badge:Internal). Shown operations
keep the order of the first term they match, so a list of operationIds shows them in that
order (unless sort-endpoints-by is set). | (empty) | |
Allowed: true shows each tag's name and description above its
operations. Off by default: a mini usually shows a few of a tag's operations, which its
description would not match. <rapi-doc> always shows
tags. | false | |
match-paths#Deprecated | [REMOVED] Use filter-operations: a path glob (/pet/**), a method and path, or operationIds. | — |
match-type#Deprecated | Allowed: [REMOVED] filter-operations matches exact terms and path globs, not substrings or regular expressions. | includes |
remove-endpoints-with-badge-label-as#Deprecated | [REMOVED] Use filter-operations="!badge:Beta". | — |
Layout & Scrolling Attributes#4
| Attribute Name | Description & Allowed Values | Default |
|---|---|---|
Allowed: Request and response side by side (row), or one above the
other (column). | row | |
Allowed: Shows operations open instead of collapsed. | false | |
Height of the response panel, as a CSS length. | 300px | |
Allowed: Shows the summary on a collapsed operation. | true |
Schemas Attributes#4
| Attribute Name | Description & Allowed Values | Default |
|---|---|---|
Allowed: Selects which tab is active by default, and listed first, for request bodies, responses and
object parameters: 'schema' (data contract model) or 'example' (sample JSON payload). | example | |
Allowed: Controls the visual representation of complex JSON schemas in request and response panels.
'tree' provides an interactive collapsible tree view; 'table' renders structured tabular rows. | tree | |
Initial depth level for auto-expanding complex nested schema properties and sub-objects (the
default expands all levels). | 99999 | |
Allowed: Controls whether schema field constraints, validation rules, and descriptions are fully
expanded by default or collapsed to a single line. | false |
Try & Servers Attributes#6
| Attribute Name | Description & Allowed Values | Default |
|---|---|---|
Allowed: Pre-populates interactive request parameter inputs and request body fields using example values
defined in the OpenAPI spec. | true | |
Selects which server URL from the spec's servers list should be selected by default. | (empty) | |
Custom API server base URL. Overrides the servers array defined in the OpenAPI specification.
Particularly useful when sharing a single spec across development, staging, and production
environments. | (empty) | |
Allowed: Enables the interactive "TRY" console allowing users to test live API calls directly from their
browser. Besides true and false, it takes the terms of filter-operations
to turn Try on only for the operations they select: !deprecated
!tag:pending-implementation keeps it off for deprecated operations and those tagged
pending-implementation. The others keep their request documentation and show a disabled TRY
DISABLED button. The Authentication section stays usable unless it is false. | true | |
Allowed: When set to true, generates and displays copyable cURL
commands directly within the endpoint documentation prior to clicking "TRY". | false | |
Allowed: Configures credentials mode for cross-origin browser Fetch requests as defined in the Fetch Standard, enabling transmission of cookies and Authorization headers
in CORS requests. | (empty) |
Authentication Attributes#7
| Attribute Name | Description & Allowed Values | Default |
|---|---|---|
Allowed: Keeps API keys, bearer tokens and OAuth access tokens in localStorage across page reloads; an
OAuth token is dropped once it expires. Basic credentials and OAuth client secrets are never
stored. | false | |
Name of the header or query parameter used when transmitting the API key in interactive console
requests. | (empty) | |
Allowed: Specifies whether the API key is passed as an HTTP request header or query parameter. | header | |
Pre-configured API key value sent during interactive console requests. Can also be set or
overwritten directly in the UI. | (empty) | |
Relative or absolute path to the OAuth receiver HTML file for handling authorization
redirection callbacks. | oauth-receiver.html | |
Custom query parameters appended to the OAuth2 authorization URL query string (e.g. proxy
launch tokens, prompt, audience). Supported Formats:
| (empty) | |
Custom parameters included in the POST request body sent to the OAuth2 token endpoint (e.g.
custom proxy parameters, resource, audience). Supported Formats:
| (empty) |
Mock Server Attributes#5
| Attribute Name | Description & Allowed Values | Default |
|---|---|---|
Allowed: Enables the built-in, zero-dependency in-browser mock server. Transparently intercepts outgoing
network requests (both RapiDoc's Try console and host application fetch/XHR calls) and serves
mock responses based on OpenAPI examples or generated from schemas. | false | |
HTTP status code to answer with, or several separated by commas, used in turn per operation
(503, 503, 200: two failures, then a success); a random: prefix picks one at random for each call (random:200, 500), cycle: says in turn
explicitly. Or a JSON map by operation, each with its own codes and prefix ({ "POST /orders": "cycle:503, 200", "*": "200" }). Set it to an empty string to
use the first 2xx response in the spec. | 200 | |
Allowed: Deprecated: put the strategy in front of the codes in mock-server-status-code instead (random:200, 500). How codes without a prefix are picked: 'cycle' uses them in
turn per operation (the default); 'random' picks one for each call; 'first' always answers the
first code, the same as giving only that code. | cycle | |
Simulated network latency in milliseconds before resolving mock responses. Useful for testing
client loading spinners and optimistic UI updates. | — | |
Allowed: Logs one line per answered request (method, path and status code) to the browser console. | false |
Theme Attributes#4
| Attribute Name | Description & Allowed Values | Default |
|---|---|---|
Allowed: Brand color preset, or a custom brand color as a hex code. Each preset defines a dark and a
light palette. | amber | |
Allowed: Base color scheme mode. 'system' automatically matches the user's OS preference. 'auto' follows
the host page: it reads the page's CSS color-scheme (for example
:root[data-theme='light'] { color-scheme: light }, as Starlight sets it) and
updates when the page switches theme; when the page declares none, it falls back to the OS
preference. | dark | |
Allowed: Corner radius scale applied across cards, buttons, badges, inputs, and dialogs. | sm | |
Allowed: Relative scale factor for typography and UI elements across the documentation portal. | default |
JavaScript API
DOM Methods#
Called on the <rapi-doc-mini> element, for example document.querySelector('rapi-doc-mini').
Programmatic Control Example
const mini = document.querySelector('rapi-doc-mini');
// Show another operation, as you would write it in filter-operations
mini.showOperation('POST /pet');
// Give the Try console a key, so readers don't have to
mini.setApiKey('api_key', 'demo-key');| Method Name | Description & Usage |
|---|---|
Programmatically loads a new OpenAPI specification. Accepts either a string URL or a valid
in-memory JSON/JavaScript spec object. The download and view buttons and the header's spec URL
box follow the spec loaded: its URL, or none for a spec object (the spec download buttons are
then hidden). | |
Programmatically supplies username and password credentials for an HTTP Basic security scheme
declared in the spec. | |
Programmatically provides the token or key for a declared API Key, Bearer Token or OAuth
security scheme. Optional options.note says where the key
came from (for example the reader's sign-in); the Authentication section shows it in place of
that scheme's form, with a link to open the form. Changing or removing the key drops the note. | |
Removes every API key, token and credential set on the element. | |
Expands one operation and scrolls it into view. operation is
its operationId (getPetById) or its method and path (GET /pet/{petId}). Resolves to false when the element shows no such operation (not loaded yet, or left out by
filter-operations). | |
Programmatically switches the active target API server URL. |
Runtime Hooks
Lifecycle & Console Events#
CustomEvents dispatched by <rapi-doc-mini>. Listen to them with addEventListener; the payload is in e.detail.
| Event Name | Description & Payload |
|---|---|
Dispatched after the OpenAPI specification has been fully fetched, parsed,
resolved, and rendered into the DOM. Provides the resolved spec object in e.detail. |