redoc 3.0.0-rc.1 → 3.0.0-rc.3

package/README.md

@@ -29,11 +29,7 @@ By default Redoc offers a three-panel, responsive layout:
 - The central panel contains the documentation.
 - The right panel contains request and response examples.
 
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="./images/demo-dark.png">
-  <source media="(prefers-color-scheme: light)" srcset="./images/demo-light.png">
-  <img alt="Redoc demo" src="./images/demo-light.png">
-</picture>
+<img alt="Redoc demo" src="./images/redoc-layouts.gif">
 
 ## Live demo
 

package/bundles/redoc.d.ts

@@ -1,7 +1,5 @@
 import type { AdmonitionProps } from '@redocly/theme/components/Admonition/Admonition';
 import type { AsyncApiConfig } from '@redocly/config';
-import type { ConfigureRequestValues } from '@redocly/theme/ext/configure';
-import type { ConfigureServerRequestValues } from '@redocly/theme/ext/configure';
 import type { EventType } from '@redocly/redoc-opentelemetry';
 import { FC } from 'react';
 import type { GraphQLConfig } from '@redocly/config';
@@ -25,14 +23,14 @@ declare type AdmonitionNode = {
 declare type AnalyticsEvent = {
     eventType: AnalyticsEventType;
     resource: 'Redocly_CodeSample' | 'Redocly_Operation';
-    action: 'LanguageSwitched' | 'PanelToggled' | 'CodeSampleCopied' | 'TargetServerSwitched';
+    action: 'LanguageSwitched' | 'CodeSampleCopied' | 'TargetServerSwitched';
     operationId?: string;
     operationPath: string;
     operationHttpVerb: string;
     operationSummary?: string | Record<string, unknown>;
 };
 
-declare type AnalyticsEventType = 'CodeSampleLanguageSwitched' | 'CodeSampleCopied' | 'OperationServerExpanded' | 'PanelToggle' | 'TargetServerSwitched';
+declare type AnalyticsEventType = 'CodeSampleLanguageSwitched' | 'CodeSampleCopied' | 'OperationServerExpanded' | 'TargetServerSwitched';
 
 declare type ApiDocsMetadata = {
     title?: string;
@@ -61,7 +59,6 @@ declare type ApiDocsOptions = {
     codeSamples?: CodeSamplesConfig;
     events: Events;
     hidePropertiesPrefix: boolean;
-    dynamicRequestValues?: ConfigureRequestValues | ConfigureServerRequestValues;
     protocol?: ProtocolVariant;
     scrollYOffset: () => number;
     hideLoading: boolean;
@@ -84,7 +81,6 @@ declare type ApiItem = ResolvedNavItem & {
 
 declare type ApiItemContent = {
     contentType: ContentType;
-    seo?: SeoData;
     itemVariant?: ItemVariant;
     meta?: ItemMeta;
     children: ContentNode[];
@@ -102,7 +98,7 @@ declare const apiSpecType: {
 declare type ApiStore = {
     schemaStore: Record<string, SchemaEntry>;
     exampleStore: Record<string, ExampleEntry>;
-    securitySchemeStore: Record<string, SecuritySchemeEntry_2>;
+    securitySchemeStore: Record<string, SecuritySchemeEntry>;
     graphqlMeta?: GraphqlStoreMeta;
     servers?: ServerData[];
     mcp?: McpData;
@@ -118,6 +114,24 @@ declare type AsyncApiExternalDocs = {
 
 declare type AsyncAPISchema = JSONSchema7 | MultiFormatSchemaObject;
 
+declare type AsyncApiSecuritySchemeType = ObjectValues<typeof asyncApiSecuritySchemeType>;
+
+declare const asyncApiSecuritySchemeType: {
+    readonly USER_PASSWORD: 'userPassword';
+    readonly API_KEY: 'apiKey';
+    readonly X509: 'X509';
+    readonly SYMMETRIC_ENCRYPTION: 'symmetricEncryption';
+    readonly ASYMMETRIC_ENCRYPTION: 'asymmetricEncryption';
+    readonly HTTP_API_KEY: 'httpApiKey';
+    readonly HTTP: 'http';
+    readonly OAUTH2: 'oauth2';
+    readonly OPEN_ID_CONNECT: 'openIdConnect';
+    readonly PLAIN: 'plain';
+    readonly SCRAM_SHA256: 'scramSha256';
+    readonly SCRAM_SHA512: 'scramSha512';
+    readonly GSSAPI: 'gssapi';
+};
+
 declare type AsyncApiServerBinding = {
     kafka?: AsyncApiServerKafkaBinding;
 };
@@ -191,7 +205,7 @@ declare type BreadcrumbItem = {
 };
 
 declare type BrokerData = {
-    /** Server host (3.x `host`, 2.x `url`); absent only for invalid documents. */
+    /** Server host; absent only for invalid documents. */
     url?: string;
     description?: string | Node_2[] | Node_2;
     name?: string;
@@ -209,6 +223,7 @@ declare type BrokerData = {
     tags?: AsyncApiTag[];
     externalDocs?: AsyncApiExternalDocs;
     bindings?: AsyncApiServerBinding;
+    security?: SecurityRequirementDetail[];
 };
 
 declare type BrokersNode = SingleChildPanelBase<typeof panelKind.BROKERS>;
@@ -236,8 +251,6 @@ declare type CallbackPayloadPanelItem = BaseExamplePanelItem & {
         variables?: Record<string, {
             default?: string;
         }>;
-        /** Set on entries injected by `mergeInMockServer` (never present in specs). */
-        isMockServer?: boolean;
     }[];
     definitionSamples?: DefinitionCodeSample_2[];
     mediaTypes?: string[];
@@ -270,22 +283,12 @@ declare type CodeSamplePanelItem = BaseExamplePanelItem & {
         variables?: Record<string, {
             default?: string;
         }>;
-        /** Set on entries injected by `mergeInMockServer` (never present in specs). */
-        isMockServer?: boolean;
     }[];
     exampleIds?: string[];
     mediaTypes?: string[];
     mediaTypeSchemas?: Record<string, MediaTypeContent>;
 };
 
-declare type CodeSampleRequestValues = {
-    security?: Record<string, unknown>;
-    envVariables?: Record<string, string>;
-    serverEnvVariables?: Record<string, Record<string, string>>;
-    body?: unknown;
-    serverBody?: Record<string, unknown>;
-};
-
 /**
  * Community edition: generated code samples are not included. The language
  * list survives only to drive the payload tab and `x-codeSamples` matching.
@@ -333,8 +336,6 @@ declare type CodeSampleSource = {
     definitionSamples?: DefinitionCodeSample[];
     /** Response status codes (for generators that include expected status) */
     responseCodes?: string[];
-    /** Configure request values (security credentials, env vars, per-server env vars) */
-    requestValues?: CodeSampleRequestValues;
     /** Raw pointer into the spec (for deep linking) */
     pointer?: string;
     /** Docs route slug of the operation page, relative to the routing base path
@@ -377,7 +378,8 @@ declare const contentType: {
     readonly ITEM: 'item';
 };
 
-export declare function convertSwagger2OpenAPI(spec: GenericObject): Promise<OpenAPIDefinition>;
+/** Promise form of `convertSwaggerToOpenApi`; rejects with the error it throws. */
+export declare const convertSwagger2OpenAPI: (document: Record<string, unknown>) => Promise<OpenAPIDefinition>;
 
 declare type DefinitionCodeSample = {
     lang: string;
@@ -434,7 +436,6 @@ declare type EnterpriseOnlyOptionKey = 'licenseKey' | 'hideReplay' | 'mockServer
 declare type Events = {
     codeSamplesLanguageSwitch?: (event: CodeSamplesLanguageSwitchedEvent) => void;
     codeSamplesCopy?: (event: CodeSamplesCopiedEvent) => void;
-    panelToggle?: (event: PanelToggleEvent) => void;
     targetServerSwitch?: (event: TargetServerSwitchedEvent) => void;
 };
 
@@ -446,6 +447,8 @@ declare type ExampleEntry = {
     description?: string | Node_2 | Node_2[];
     mediaType?: string;
     externalValue?: string;
+    /** Header values of an AsyncAPI message example. */
+    headers?: Record<string, unknown>;
 };
 
 declare type ExamplePanelItem = PayloadExamplesPanelItem | CodeSamplePanelItem | ResponseExamplesPanelItem | CallbackPayloadPanelItem | GraphQLQueryPanelItem | GraphQLResponsePanelItem | GraphQLVariablesPanelItem | GraphQLTypeSamplePanelItem;
@@ -480,6 +483,13 @@ declare type ExternalLinkPanelItem = {
     copyContent?: string;
 };
 
+declare type FormFieldEncoding = {
+    contentType?: string;
+    style?: string;
+    explode?: boolean;
+    allowReserved?: boolean;
+};
+
 declare type GraphQLContact = {
     name?: string;
     url?: string;
@@ -684,6 +694,10 @@ declare type ItemContentNode = {
             url: string;
             description?: string | Node_2[] | Node_2;
         };
+        correlationId?: {
+            location: string;
+            description?: string | Node_2[] | Node_2;
+        };
     }>;
     values?: Array<{
         name: string;
@@ -694,7 +708,6 @@ declare type ItemContentNode = {
 };
 
 declare type ItemMeta = {
-    sourceId?: string;
     name?: string;
     deprecated?: boolean;
     isWebhook?: boolean;
@@ -797,7 +810,7 @@ declare type MarkdownParser = (markdown: string, sanitizeOptions?: {
  * - `render` turns the parsed value into React.
  *
  * The standalone build supplies a Markdoc-based adapter (`createMarkdocAdapter`). Embedders that
- * pre-parse upstream (e.g. realm) supply a `parse` no-op plus their own `render`, so the Markdoc
+ * pre-parse upstream supply a `parse` no-op plus their own `render`, so the Markdoc
  * parser never enters their client bundle.
  */
 declare type MarkdownRenderer = (parsed: unknown) => ReactNode;
@@ -873,6 +886,7 @@ declare type McpTool = {
 declare type MediaTypeContent = {
     schemaId?: string;
     exampleIds?: string[];
+    encoding?: Record<string, FormFieldEncoding>;
 };
 
 declare type MediaTypeEntry = {
@@ -981,7 +995,6 @@ declare type OAuthFlowsData = {
         tokenUrl: string;
         refreshUrl?: string;
         scopes: Record<string, string>;
-        'x-defaultClientId'?: string;
     };
 };
 
@@ -1019,6 +1032,9 @@ declare type OpenAPIComponents = {
     callbacks?: {
         [name: string]: Referenced<OpenAPICallback>;
     };
+    mediaTypes?: {
+        [name: string]: Referenced<OpenAPIMediaType>;
+    };
 };
 
 declare type OpenAPIContact = {
@@ -1044,7 +1060,6 @@ declare type OpenAPIDefinition = {
         tags: Array<string>;
     }>;
     'x-keywords'?: unknown;
-    'x-root'?: OpenAPISchema;
 };
 
 declare type OpenAPIDiscriminator = {
@@ -1160,7 +1175,7 @@ declare type OpenAPIParameter = {
         [media: string]: Referenced<OpenAPIExample>;
     };
     content?: {
-        [media: string]: OpenAPIMediaType;
+        [media: string]: Referenced<OpenAPIMediaType>;
     };
     encoding?: Record<string, OpenAPIEncoding>;
     const?: unknown;
@@ -1204,7 +1219,7 @@ declare type OpenAPIRequestBody = {
     description?: string | Node_2[] | Node_2;
     required?: boolean;
     content?: {
-        [mime: string]: OpenAPIMediaType;
+        [mime: string]: Referenced<OpenAPIMediaType>;
     };
     'x-examples'?: {
         [mime: string]: {
@@ -1222,7 +1237,7 @@ declare type OpenAPIResponse = {
         [name: string]: Referenced<OpenAPIHeader>;
     };
     content?: {
-        [mime: string]: OpenAPIMediaType;
+        [mime: string]: Referenced<OpenAPIMediaType>;
     };
     links?: {
         [name: string]: Referenced<OpenAPILink>;
@@ -1308,7 +1323,6 @@ declare type OpenAPISecurityScheme = {
     in?: SecuritySchemeIn;
     scheme?: string;
     bearerFormat: string;
-    'x-defaultClientId'?: string;
     deprecated?: boolean;
     oauth2MetadataUrl?: string;
     flows: {
@@ -1316,33 +1330,28 @@ declare type OpenAPISecurityScheme = {
             refreshUrl?: string;
             scopes: Record<string, string>;
             authorizationUrl: string;
-            'x-defaultClientId'?: string;
         };
         deviceAuthorization?: {
             deviceAuthorizationUrl: string;
             scopes: Record<string, string>;
             tokenUrl: string;
             refreshUrl?: string;
-            'x-defaultClientId'?: string;
         };
         password?: {
             refreshUrl?: string;
             scopes: Record<string, string>;
             tokenUrl: string;
-            'x-defaultClientId'?: string;
         };
         clientCredentials?: {
             refreshUrl?: string;
             scopes: Record<string, string>;
             tokenUrl: string;
-            'x-defaultClientId'?: string;
         };
         authorizationCode?: {
             refreshUrl?: string;
             scopes: Record<string, string>;
             authorizationUrl: string;
             tokenUrl: string;
-            'x-defaultClientId'?: string;
         };
     };
     openIdConnectUrl?: string;
@@ -1353,8 +1362,6 @@ declare type OpenAPIServer = {
     description?: string | Node_2 | Node_2[];
     name?: string;
     variables?: OpenAPIServerVariables;
-    /** Set on entries injected by `mergeInMockServer` (never present in specs). */
-    isMockServer?: boolean;
 };
 
 declare type OpenAPIServerVariable = {
@@ -1452,17 +1459,6 @@ declare type PanelTag = {
     icon?: string;
 };
 
-declare type PanelToggleEvent = AnalyticsEvent & {
-    panelType: PanelType;
-    state: 'expanded' | 'collapsed';
-    operationId: string;
-    operationPath: string;
-    operationHttpVerb: string;
-    operationSummary?: string | Record<string, unknown>;
-};
-
-declare type PanelType = 'request' | 'responses' | 'request-samples' | 'response-samples';
-
 declare type ParameterData = {
     name: string;
     in?: string;
@@ -1487,10 +1483,6 @@ declare type ParameterEntry = {
     style?: string;
     explode?: boolean;
     allowReserved?: boolean;
-    /** Per-server example overrides: serverUrl → example value */
-    serverValues?: Record<string, {
-        example?: unknown;
-    }>;
 };
 
 declare const parameterLocation: {
@@ -1513,7 +1505,14 @@ declare type PayloadExamplesPanelItem = BaseExamplePanelItem & {
     }>;
 };
 
-export declare function prepareApiDocs({ spec, specUrl, options, basePath }: Pick<RedocStandaloneProps, 'spec' | 'specUrl' | 'options' | 'basePath'>): Promise<PreparedApiDocs>;
+/**
+ * Resolves the spec and builds the item model. `convertedDownload: false` keeps the default
+ * download on `specUrl` for an AsyncAPI 2.x source instead of a `blob:` URL of the converted
+ * document, which a server pass cannot create; the caller revokes any `blob:` download URL.
+ */
+export declare function prepareApiDocs({ spec, specUrl, options, basePath, convertedDownload }: Pick<RedocStandaloneProps, 'spec' | 'specUrl' | 'options' | 'basePath'> & {
+    convertedDownload?: boolean;
+}): Promise<PreparedApiDocs>;
 
 declare type PreparedApiDocs = {
     items: ApiItem[];
@@ -1535,7 +1534,6 @@ declare type RawApiDocsOptions = EditionRedocConfig & EditionAsyncApiConfig & Ed
     disableTelemetry?: boolean;
     requiredPropsFirst?: boolean;
     protocol?: ProtocolVariant;
-    dynamicRequestValues?: ConfigureRequestValues | ConfigureServerRequestValues;
     layout?: EditionRedocConfig['layout'] | EditionAsyncApiConfig['layout'] | EditionGraphQLConfig['layout'];
 };
 
@@ -1582,7 +1580,7 @@ export declare type RedocProps = RedoclyApiDocsInnerProps & {
 export declare const RedocStandalone: ({ spec, specUrl, options, basePath, logo, markdownAdapter, onLoaded, children, }: RedocStandaloneProps) => ReactElement | null;
 
 export declare type RedocStandaloneProps = {
-    /** Parsed API description object, or a GraphQL SDL string. */
+    /** Parsed API description object, its JSON or YAML text, or a GraphQL SDL string. */
     spec?: Record<string, unknown> | string;
     /** URL of the API description. Ignored when `spec` is provided. */
     specUrl?: string;
@@ -1634,7 +1632,6 @@ declare type ResponseExamplesPanelItem = BaseExamplePanelItem & {
     /** Webhook response: the client sends it, so samples drop readOnly like a request. */
     isEvent?: boolean;
     hideHeaderTitle?: boolean;
-    exampleKey?: string;
 };
 
 declare type Sample = {
@@ -1658,25 +1655,18 @@ declare const schemaKind: {
 
 declare type SecurityNode = {
     nodeType: typeof nodeTypes.SECURITY;
-    requirements: Array<{
-        schemes: SecuritySchemeDetail[];
-    }>;
+    requirements: SecurityRequirementDetail[];
 };
 
 /** One AND-group: all schemes in the array must be satisfied together */
 declare type SecurityRequirement = {
-    schemes: SecuritySchemeEntry[];
+    schemes: SecuritySchemeEntry_2[];
     scopes: string[];
 };
 
-declare type SecuritySchemeCredentials = {
-    'x-defaultAccessToken'?: string;
-    'x-defaultTokenType'?: string;
-    'x-defaultClientId'?: string;
-    'x-defaultClientSecret'?: string;
-    'x-defaultUsername'?: string;
-    'x-defaultPassword'?: string;
-    scopes?: string[];
+/** Schemes required together; separate requirements are alternatives. */
+declare type SecurityRequirementDetail = {
+    schemes: SecuritySchemeDetail[];
 };
 
 declare type SecuritySchemeDetail = {
@@ -1690,47 +1680,33 @@ declare type SecuritySchemeDetail = {
     description?: string | Node_2[] | Node_2;
     openIdConnectUrl?: string;
     oauth2MetadataUrl?: string;
-    flows?: SecuritySchemeEntry_2['flows'];
+    flows?: SecuritySchemeEntry['flows'];
     deprecated?: boolean;
 };
 
 declare type SecuritySchemeEntry = {
     id: string;
-    type: Exclude<SecuritySchemeType, typeof securitySchemeType.MUTUAL_TLS>;
-    name?: string;
-    in?: SecuritySchemeIn;
+    type: SecuritySchemeType | AsyncApiSecuritySchemeType;
     scheme?: string;
     bearerFormat?: string;
+    description?: string | Node_2[] | Node_2;
+    in?: SecuritySchemeIn | 'user' | 'password';
+    paramName?: string;
+    scopes?: string[];
     openIdConnectUrl?: string;
+    deprecated?: boolean;
+    oauth2MetadataUrl?: string;
     flows?: OAuthFlowsData;
-    'x-defaultAccessToken'?: string;
-    'x-defaultTokenType'?: string;
-    'x-defaultClientId'?: string;
-    'x-defaultClientSecret'?: string;
-    'x-defaultUsername'?: string;
-    'x-defaultPassword'?: string;
-    /** Per-server auth overrides */
-    serverValues?: Record<string, SecuritySchemeCredentials>;
 };
 
 declare type SecuritySchemeEntry_2 = {
     id: string;
-    type: SecuritySchemeType;
+    type: Exclude<SecuritySchemeType, typeof securitySchemeType.MUTUAL_TLS>;
+    name?: string;
+    in?: SecuritySchemeIn;
     scheme?: string;
     bearerFormat?: string;
-    description?: string | Node_2[] | Node_2;
-    in?: SecuritySchemeIn;
-    paramName?: string;
     openIdConnectUrl?: string;
-    deprecated?: boolean;
-    oauth2MetadataUrl?: string;
-    'x-defaultClientId'?: string;
-    'x-defaultAccessToken'?: string;
-    'x-defaultTokenType'?: string;
-    'x-defaultClientSecret'?: string;
-    'x-defaultUsername'?: string;
-    'x-defaultPassword'?: string;
-    serverValues?: Record<string, SecuritySchemeCredentials>;
     flows?: OAuthFlowsData;
 };
 
@@ -1753,13 +1729,6 @@ declare const securitySchemeType: {
     readonly MUTUAL_TLS: 'mutualTLS';
 };
 
-declare type SeoData = {
-    title?: string;
-    description?: string;
-    keywords?: string;
-    image?: string;
-};
-
 declare type ServerData = {
     url: string;
     name?: string;
@@ -1777,8 +1746,6 @@ declare type ServerEntry = {
     name?: string;
     description?: string;
     variables?: Record<string, ServerVariable>;
-    /** Set on entries injected by `mergeInMockServer` (never present in specs). */
-    isMockServer?: boolean;
 };
 
 declare type ServersNode = SingleChildPanelBase<typeof panelKind.SERVERS>;