RapiDoc Mini
<rapi-doc> is a whole API reference with navigation and search. <rapi-doc-mini> shows only the operations you pick, with their parameters, schemas and Try console, so you can put a working endpoint in the middle of a tutorial, changelog or wiki page without an <iframe>. It is in the same bundle as <rapi-doc>.
Show one endpoint
Section titled “Show one endpoint”Point spec-url at your spec and choose operations with filter-operations:
<script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
<rapi-doc-mini spec-url="https://petstore.swagger.io/v2/swagger.json" filter-operations="GET /pet/{petId}"></rapi-doc-mini>Choose operations
Section titled “Choose operations”filter-operations is a list of terms, separated by spaces or commas. An operation is shown when it matches any term (every operation is, when there is none) and no term that starts with !.
| Term | Shows |
|---|---|
getPetById |
The operation with that operationId (exact, case-sensitive). |
GET /pet/{petId} |
That method and path. |
/pet/{petId} |
Every method on that path. |
/pet/*, /pet/** |
Paths matching the glob: * is one path segment, ** any number of segments, /pet itself included. |
tag:store |
Operations with that tag. Quote a name with spaces: tag:"Pet Store". |
badge:Beta |
Operations with that x-badges label, or an OpenAPI 3.2 tag of kind: badge (by its label or name). |
deprecated |
Deprecated operations. |
!<term> |
Leaves out what the term matches, as in !badge:Internal or !deprecated. |
Methods, paths, tags and badge labels are compared without case. Paths are matched whole, never as part of a longer path: POST /user does not show POST /user/createWithList; use /user/** for everything under /user.
An operationId is matched only when the term is none of the other kinds: an id that starts with tag: or badge:, or is the word deprecated, is read as that kind instead. Select such an operation by its method and path (GET /path).
allow-try takes the same terms, to turn Try on only for the operations they select: allow-try="!deprecated !tag:pending-implementation". The operations they leave out keep their request documentation and show a disabled TRY DISABLED button.
The operations are shown in the order of the first term they match, so a list of operationIds keeps its order, unless sort-endpoints-by is set:
<rapi-doc-mini spec-url="https://petstore.swagger.io/v2/swagger.json" filter-operations="placeOrder getOrderById"></rapi-doc-mini>
<!-- Everything tagged store, except the delete --><rapi-doc-mini spec-url="https://petstore.swagger.io/v2/swagger.json" filter-operations="tag:store !DELETE /store/order/{orderId}"></rapi-doc-mini>Recipes
Section titled “Recipes”<rapi-doc-mini spec-url="/specs/reqres.yaml" filter-operations="GET /users/{userId} POST /users" schema-style="table"></rapi-doc-mini><rapi-doc-mini spec-url="/specs/reqres.yaml" filter-operations="POST /users" paths-expanded="true" layout="column"></rapi-doc-mini>Each element loads its own spec, so one page can walk through a flow that spans services:
<rapi-doc-mini spec-url="https://api.example.com/auth/openapi.yaml" filter-operations="POST /oauth/token"></rapi-doc-mini><rapi-doc-mini spec-url="https://api.example.com/billing/openapi.yaml" filter-operations="POST /charges"></rapi-doc-mini>The key is sent with every Try request when all three api-key-* attributes are set:
<rapi-doc-mini spec-url="/specs/api.yaml" filter-operations="GET /orders" api-key-name="X-API-Key" api-key-location="header" api-key-value="test-key-123"></rapi-doc-mini>If the spec can’t be loaded, the element renders nothing and logs the error to the browser console.
Show an operation from a script
Section titled “Show an operation from a script”showOperation(operation) expands one operation and scrolls it into view. Pass its operationId or its method and path; it resolves to false when the element does not show that operation (the spec is not loaded yet, or filter-operations leaves it out).
await document.querySelector('rapi-doc-mini').showOperation('GET /pet/{petId}');Next to a workflow
Section titled “Next to a workflow”<rapi-flow> pairs with one <rapi-doc-mini> per API its Arazzo workflow calls. Name the API with arazzo-source; <rapi-flow> then sets the mini’s filter-operations to the workflow’s calls to that API, in step order, and clicking a step shows its operation in the mini.
<rapi-flow arazzo-url="/workflows/ship-a-parcel.arazzo.yaml" for="rates-api shipments-api"></rapi-flow><rapi-doc-mini id="rates-api" arazzo-source="rates" spec-url="/specs/rates.yaml"></rapi-doc-mini><rapi-doc-mini id="shipments-api" arazzo-source="shipments" spec-url="/specs/shipments.yaml"></rapi-doc-mini>Attributes
Section titled “Attributes”Every attribute, method and event, grouped by what it changes, is on the <rapi-doc-mini> API reference, read from the element’s source.
<rapi-doc> or <rapi-doc-mini>?
Section titled “<rapi-doc> or <rapi-doc-mini>?”| Feature / Goal | <rapi-doc> | <rapi-doc-mini> |
|---|---|---|
| Best for | A complete API reference, on its own page | One or a few endpoints inside a blog post, tutorial or changelog |
| Navigation sidebar and search | Yes | No |
| URL hash routing | Yes (update-route) | No: never changes the page URL |
| Tag names and descriptions | Always: tags are its sections and sidebar groups | Off by default (show-tags="true" turns them on) |
| Try console | Yes | Yes |
| Sizing | Fills the height you give it, usually the viewport | Grows with its content inside any container |
| Render modes | read, view and focused | One: the matched operations |