RapiDoc API Specification

Programmatically loads a new OpenAPI specification. Accepts either a string URL or a valid in-memory JSON/JavaScript spec object.

Programmatically scrolls the viewport to focus on a specific endpoint section. The path argument must be formatted as {method}-{path} (e.g., get-/user/login).

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 or Bearer Token security scheme.

Programmatically switches the active target API server URL.

<html>
  ...
  <rapi-doc id="the-doc" spec-url="https://.../spec.yaml"></rapi-doc>
  <script>
    window.addEventListener('DOMContentLoaded', () => {
      const rapidocEl = document.getElementById('the-doc');
      rapidocEl.addEventListener('spec-loaded', () => {
        rapidocEl.setApiServer(window.location.origin + "/api");
      });
    });
  </script>
  ...
</html>

Dispatched before rendering starts. Provides the parsed OpenAPI specification object via e.detail.spec, allowing programmatic modifications before the UI tree is built.

Dispatched after the OpenAPI specification has been fully fetched, parsed, resolved, and rendered into the DOM. Provides the resolved spec object in e.detail.

Dispatched when a user clicks "TRY" before the network request is initiated. Provides a mutable Request-like object via e.detail.request to append headers, rewrite parameters, or modify payloads, along with an AbortController via e.detail.controller to abort requests conditionally.

Example: Append custom authorization headers before sending:

 rapidocEl.addEventListener('before-try', (e) => {
  if (e.detail.request.method === 'POST') {
    e.detail.request.headers.append('X-Tenant-ID', 'corp-acme-123');
  }
}); 

Example: Append query parameters to all GET requests:

 rapidocEl.addEventListener('before-try', (e) => {
  if (e.detail.request.method === 'GET') {
    const url = new URL(e.detail.request.url);
    url.searchParams.append('client_version', '2.4.0');
    e.detail.request.url = url.toString();
  }
}); 

Example: Abort specific requests conditionally:

 rapidocEl.addEventListener('before-try', (e) => {
  if (e.detail.request.method === 'DELETE') {
    alert('DELETE operations are disabled in this sandbox environment.');
    e.detail.controller.abort();
  }
}); 

Dispatched after a try request completes. Provides e.detail.request and e.detail.response. In the event of a network or protocol error, provides request and error objects.

Dispatched when an in-flight API try request is aborted by the user or programmatically via AbortController.

Dispatched when the active target API server is modified in the dropdown.

Dispatched immediately before opening the OAuth authorization popup window. Provides e.detail.securitySchemeId, e.detail.flowType, e.detail.authUrl, and mutable e.detail.authParams (URLSearchParams). Calling e.preventDefault() cancels opening the authorization window.

Example: Dynamically inject a launch token or proxy parameter:

 rapidocEl.addEventListener('before-authorize', (e) => {
  e.detail.authParams.set('launch', 'xyz123');
}); 

Dispatched immediately before sending the POST request to the OAuth2 token endpoint. Provides e.detail.securitySchemeId, e.detail.grantType, e.detail.tokenUrl, mutable e.detail.params (URLSearchParams), e.detail.headers (Headers), and mutable e.detail.request. Calling e.preventDefault() cancels the token request.

Example: Add a custom token audience or header:

 rapidocEl.addEventListener('before-token-request', (e) => {
  e.detail.params.set('audience', 'https://api.mycompany.com');
  e.detail.headers.set('X-Client-Version', '1.0.0');
}); 

Any standard markup placed directly inside the `` tag renders immediately below the header bar and above the specification info overview.

Custom HTML or image markup to replace the default brand logo in the top header bar.

Custom HTML elements rendered in the top header bar following the spec URL input controls.

Custom HTML elements rendered at the bottom of the documentation canvas.

Custom image or branding markup placed at the top of the sidebar navigation panel (available in read mode).

Custom HTML rendered inside the overview section at the top of the document. Link directly to this anchor using #overview.

Custom HTML rendered inside the server configuration section located under the overview container. Link directly using #servers.

Custom HTML rendered inside the authentication controls panel under the overview section. Link directly using #auth.

Custom HTML displayed directly above the operations list. Use this slot to provide global announcements, common headers, or usage instructions applicable across all API calls. Link directly using #operations-top.

Inserts custom HTML content underneath a specific tag grouping identified by tag name.

Inserts custom HTML into a specific endpoint section. Identified by {method}-{path}, where special characters such as brackets, spaces, and hashes are replaced by hyphens (e.g. get-/pet/-petId-).

Provides multi-language code snippets (cURL, Python, JavaScript, Go, etc.) for an endpoint.

Alternative camelCase syntax for x-code-sample. Provides multi-language code snippets for an endpoint.

Annotates endpoints with short, color-coded badges (e.g., "Internal", "Beta", "v2"). Combine with the remove-endpoints-with-badge-label-as attribute to filter out restricted or internal APIs from public documentation.

Controls whether endpoints grouped under a tag start expanded or collapsed (applies in view and focused render styles).

Specifies whether a parameter's example value should be automatically populated in the interactive console input. To configure this behavior globally for all parameters, see fill-request-fields-with-example.

Specifies whether parameter example values should be visibly rendered on the documentation card.

Pre-fills the OAuth2 client ID in authentication modals.

Pre-fills the OAuth2 client secret in authentication modals.

Pre-fills default OAuth2 permission scopes in authentication modals.

Defines whether client credentials (client_id / client_secret) are sent via request body or HTTP Authorization header (request-body or header). Default is request-body.

Restricts the client authentication options available in the UI dropdown (e.g. ["request-body", "header"]).

When set to "true", enforces Proof Key for Code Exchange (PKCE) flow and prevents client secrets from being transmitted from the browser.

Object or query string defining custom parameters appended to the OAuth2 authorizationUrl query string (e.g. proxy launch tokens, prompt, audience). Supported at both security scheme and individual flow levels.

Example:

 components:
  securitySchemes:
    oauth-flow:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/oauth2/authorize
          tokenUrl: https://auth.example.com/oauth2/token
          x-authorize-params:
            launch: xyz123
            prompt: consent
            audience: https://api.mycompany.com
          scopes:
            read: Read access

Object or form parameters sent in the POST request body to the OAuth2 tokenUrl (e.g. custom proxy fields, resource, audience). Supported at both security scheme and individual flow levels.

Example:

 components:
  securitySchemes:
    oauth-flow:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/oauth2/authorize
          tokenUrl: https://auth.example.com/oauth2/token
          x-token-params:
            audience: https://api.mycompany.com
            resource: urn:my:resource:server
          scopes:
            read: Read access