Using FlexDoc

For React applications, install the canonical client package and its stylesheet:

npm install @prauga/flexdoc-client@2.8.0

For backend frameworks, use the native adapter for your stack. The renderer assets are served locally by the adapter; a FlexDoc account or runtime CDN is not required.

See every framework install command →

Pass an OpenAPI 3.0 or 3.1 document to FlexDoc. JSON objects can be imported directly; backend adapters can also point the renderer at a served specification URL.

import { FlexDoc } from '@prauga/flexdoc-client';
import '@prauga/flexdoc-client/styles.css';
import spec from './openapi.json';

export function ApiDocs() {
  return <FlexDoc spec={spec} />;
}

FlexDoc resolves local JSON Pointer references as well as external, nested and circular references. OpenAPI 2.0 / Swagger 2.0 is not accepted; convert it to OpenAPI 3.x first.

Use the options prop to configure the reference UI, initial expansion state, Try It, code samples, themes and other renderer behavior.

<FlexDoc
  spec={spec}
  theme='dark'
  options={{
    title: 'Payments API',
    expand: 'none',
    pathInMiddlePanel: true,
    showRequestHeaders: true,
    tryIt: { enabled: true },
    codeSamples: {
      enabled: true,
      languages: ['curl', 'javascript', 'python', 'go', 'java'],
    },
  }}
/>

Enable Try It to turn each OpenAPI operation into an executable request editor. Users can edit parameters, request bodies, authentication and the selected server before sending.

<FlexDoc
  spec={spec}
  options={{
    tryIt: {
      enabled: true,
      defaultServer: 'https://staging.api.example.com',
      credentials: 'same-origin',
      requestInterceptor: (request) => ({
        ...request,
        headers: {
          ...request.headers,
          'X-Docs-Client': 'flexdoc',
        },
      }),
    },
  }}
/>

Try It uses the same canonical request model as generated code samples and API Client handoff, including server variables and supported OpenAPI parameter serialization styles.

Define security schemes in the OpenAPI document as usual. FlexDoc supports Basic and Bearer HTTP authentication, API keys in headers/query/cookies, and OAuth 2.0/OpenID Connect access-token injection.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

security:
  - bearerAuth: []

OpenAPI security alternatives are respected, including OR alternatives and multi-scheme AND requirements. Interactive OAuth grant acquisition lives in the API Client workspace; OpenAPI Try It accepts supplied OAuth/OpenID tokens.

When code samples are enabled, FlexDoc derives them from the same request that Try It builds. The 2.8 renderer supports cURL, JavaScript, Python, Go and Java samples.

options={{
  codeSamples: {
    enabled: true,
    languages: ['curl', 'javascript', 'python', 'go', 'java'],
  },
}}

Use ApiClient when you want an embeddable HTTP request editor/executor without requiring an OpenAPI document or persisted workspace.

import { ApiClient } from '@prauga/flexdoc-client';
import '@prauga/flexdoc-client/styles.css';

export function RequestPanel() {
  return (
    <ApiClient
      initialRequest={{
        method: 'GET',
        url: 'https://api.example.com/pets',
      }}
      credentials='omit'
      onExecutionComplete={(result) => {
        console.log(result.status, result.responseTime);
      }}
    />
  );
}

The standalone component supports editable URL/query/headers/body/auth, request interceptors, variables, server choices, scripts, tests and response inspection. It does not create collections or persist state by itself.

ApiClientWorkspace wraps the same request editor with collections, folders, environments, history, auth inheritance, scripts/tests, Postman import and optional IndexedDB persistence.

import { ApiClientWorkspace } from '@prauga/flexdoc-client';
import '@prauga/flexdoc-client/styles.css';

export function Workspace() {
  return (
    <ApiClientWorkspace
      persistenceKey='payments-api'
      initialRequest={{
        method: 'GET',
        url: '{{baseUrl}}/payments',
        auth: { type: 'inherit' },
      }}
    />
  );
}

The workspace is standalone: it can be used as an API-development surface even when there is no OpenAPI document on the page.

Create collections to group saved requests. Folders can be nested to arbitrary depth, and saved requests retain their collection/folder identity for history and replay.

Use collection-level configuration for shared variables and auth, then override them on a folder or individual request only when necessary.

Use {{variableName}} placeholders in request URLs, query parameters, headers and bodies. The workspace supplies collection variables and the active environment to the normal request builder.

GET {{baseUrl}}/pets/{{petId}}

Authorization: Bearer {{token}}

At execution time, collection variables are combined with host-provided variables and the active environment. Environment values take precedence when the same key appears in more than one layer.

Collections, folders and requests can use Inherit auth, No auth, Bearer, Basic, API key or OAuth 2.0. The closest explicit child setting wins; otherwise the request inherits from its parent hierarchy.

OAuth supports manual access tokens, Authorization Code with PKCE, Client Credentials, Password, Implicit and explicit refresh-token reuse. Browser OAuth flows still depend on the provider allowing the relevant redirect and CORS behavior.

Requests can run trusted JavaScript before execution and tests after the response. The shared flex.* runtime can mutate request data, collection variables and environment variables, record test results and capture console output.

// Pre-request
flex.request.headers.set('X-Run-Id', String(Date.now()));
flex.collection.set('lastRequest', 'pets');

// Post-response tests
flex.test('status is 200', () =>
  flex.expect(flex.response.code).to.equal(200)
);

flex.environment.set(
  'lastPetId',
  String(flex.response.json().id)
);

console.log('tested', flex.response.code);

The workspace keeps bounded request history with resolved execution metadata, response test results, captured script logs and originating collection/folder identity.

Replaying an entry restores the editable raw request template rather than replacing it with the fully resolved execution URL. This keeps {{variables}} useful after replay.

FlexDoc 2.8 imports Postman Collection v2.1 JSON and Postman environment JSON directly into the canonical workspace.

1. Open the API Client Workspace.
2. Choose Import Postman.
3. Select a Collection v2.1 JSON file, an environment JSON file, or both.
4. Review any compatibility warnings and import.

Supported folders, requests, variables, common auth, request bodies and compatible scripts become normal FlexDoc workspace data immediately. There is no separate Postman request engine or persistence layer.

By default, ApiClientWorkspace persists browser-local state in origin-scoped IndexedDB. Give each embedded workspace a stable key.

<ApiClientWorkspace persistenceKey='payments-api' />

// Disable persistence entirely:
<ApiClientWorkspace persistenceKey={false} />

Collections, folders, saved requests, variables, environments, auth values, scripts and history are stored as entered. FlexDoc does not encrypt persisted workspace values.

Use the CLI to serve a local specification with live reload or generate a self-contained static documentation bundle.

npm install --save-dev @prauga/flexdoc-cli@0.4.0

# Serve locally
npx @prauga/flexdoc-cli serve openapi.yaml --watch

# Build static documentation
npx @prauga/flexdoc-cli build openapi.yaml --out ./docs

The generated renderer assets are local to the output; a runtime FlexDoc CDN is not required.

Backend adapters expose the same renderer contract through native framework routing. They do not implement separate copies of Try It, schemas, API Client behavior or theming.

// Express
import { setupExpressFlexDoc } from '@prauga/flexdoc-backend';

setupExpressFlexDoc(app, '/docs', {
  specUrl: '/openapi.json',
  options: { title: 'My API', expand: 'none' },
});

2.8 packages are available for Express, Fastify, NestJS, Hono, ASP.NET Core, Spring Boot/JAX-RS and other JVM hosts, FastAPI/Starlette/Flask/Django, Laravel/Symfony, Rack/Rails, Go HTTP frameworks, Axum/Actix and Plug/Phoenix.

Open the framework install selector →

• OpenAPI 3.0.x and 3.1.x are supported; Swagger/OpenAPI 2.0 is not.
• Nested deepObject expansion is not recursive.
• Binary file picking is not yet a first-class renderer control for multipart Try It requests.
• Webhooks, callbacks, XML metadata and advanced JSON Schema conditionals are not complete first-class interactive surfaces.
• API Client scripts are trusted local JavaScript rather than a sandbox.
• Persisted workspace secrets are stored as entered in the browser origin.
• Postman compatibility is intentionally explicit: unsupported source behavior produces warnings.

For implementation details and the exact release source, see the FlexDoc 2.8 tag ↗.