OpenAPI Try it

A "Try it out" plugin for apiuikit. Fill in parameters, auth, and a body, send the request, and inspect the response — from the docs.

This package is not bundled with apiuikit. Install it and pass it as a plugin.

Install

npm install @apiuikit/openapi-try-it-plugin

Peer dependencies: apiuikit ^1.7, React 18+.

Usage

Two layouts to register here, plus a third that apiuikit provides itself.

Keep the plugins array stable by defining it outside the component or with useMemo. A new array on every render re-registers the plugins and can reset the selected tab.

You can pass plugins to OpenAPI, OpenAPIRenderer, OpenAPIProvider, or a standalone section that receives a document prop. When a section is inside a provider, it uses the provider's plugins.

Tab (default)

Fills the openapi.operation.tab slot — a Try it tab next to the built-in Reference tab.

import { OpenAPI } from "apiuikit";
import tryItPlugin from "@apiuikit/openapi-try-it-plugin";
import "apiuikit/style.css";
import doc from "./openapi.json";

const plugins = [tryItPlugin];

export default function App() {
  return <OpenAPI openapi={doc} plugins={plugins} />;
}

Button

Fills the openapi.operation.reference.supplementary slot — a Try it row on the Path side panel. Clicking it opens a modal with the request on the left and the response on the right.

import { OpenAPI } from "apiuikit";
import { createTryItButtonPlugin } from "@apiuikit/openapi-try-it-plugin";
import "apiuikit/style.css";
import doc from "./openapi.json";

const plugins = [createTryItButtonPlugin()];

export default function App() {
  return <OpenAPI openapi={doc} plugins={plugins} />;
}

Panel header — built into apiuikit

The header layout doesn't need this package. apiuikit ships it and loads it on demand:

import { OpenAPI } from "apiuikit";
import "apiuikit/style.css";
import doc from "./openapi.json";

const config = { show: { tryIt: true } };

export default function App() {
  return <OpenAPI openapi={doc} config={config} />;
}

That puts a compact Try it button in the operation panel's header, next to the close button, opening the same modal as the button layout above. It is off by default — see Configuration.

Install this package when you want a layout the built-in doesn't offer (a full tab, or a row inside the Reference panel), or when you need proxyUrl.

Several at once

import tryItPlugin, { createTryItButtonPlugin } from "@apiuikit/openapi-try-it-plugin";

const plugins = [tryItPlugin, createTryItButtonPlugin()];

Each entry point keeps its own request state — filling in parameters under one does not carry over to another. Registering more than one is supported, but one is usually what you want.

CORS

Requests go from the browser. If the API does not allow your origin, the browser will block them.

This package does not ship a proxy. If you have one, pass it:

import { createTryItPlugin } from "@apiuikit/openapi-try-it-plugin";

const plugins = [createTryItPlugin({ proxyUrl: "https://your-proxy.example.com/tryit" })];

Requests then go to ${proxyUrl}?target=<url-encoded API URL> instead of the API origin.

createTryItButtonPlugin accepts the same proxyUrl option. The built-in header layout does not take options — a host needing proxyUrl registers a plugin from this package instead.

Supported auth

| Scheme | Behavior | | --- | --- | | API key (header / query) | Input field | | HTTP Bearer | Token input | | HTTP Basic | Username + password | | OAuth2 client credentials | Fetches a token from the token URL | | OAuth2 authorization code (+ PKCE) | Login popup, then token exchange | | Other OAuth2 / OpenID Connect | Paste a token obtained elsewhere |

OAuth2 authorization-code redirect URIs must be same-origin with the page hosting apiuikit.

Cookie API keys cannot be sent from the browser (Cookie is a forbidden Fetch header).

Export

After building a request, export it as a Postman collection, an Insomnia collection, or a HAR file from the Export menu.

Development

npm install
npm run test
npm run typecheck
npm run build

Manual QA against the apiuikit playground: TESTING.md.