redoc 2.5.4 → 3.0.0-rc.1

package/typings/types/asyncapi.d.ts

@@ -0,0 +1,348 @@
+import type { Node } from '@markdoc/markdoc';
+import type { ResolvedNavItem } from '@redocly/config';
+import type { JSONSchema7 } from 'json-schema';
+import type { Referenced, ObjectValues } from './common.js';
+import type { ApiItem, StoreContext } from './store.js';
+import type { ApiDocsOptions } from './options.js';
+export type AsyncApiDefinition = {
+    asyncapi: string;
+    id?: string;
+    info: AsyncApiInfo;
+    servers?: Record<string, AsyncApiServer>;
+    defaultContentType?: string;
+    channels?: AsyncApiChannels;
+    operations?: AsyncApiOperations;
+    components?: AsyncApiComponents;
+    'x-tagGroups'?: {
+        name: string;
+        tags: string[];
+    }[];
+    'x-redocly-catalog-key'?: string;
+};
+export type AsyncApiDefinitionReferenced = {
+    asyncapi: string;
+    id?: string;
+    info: AsyncApiInfo;
+    servers?: Record<string, AsyncApiServer>;
+    defaultContentType?: string;
+    channels?: AsyncApiChannels;
+    operations?: AsyncApiOperationsReferenced;
+    components?: AsyncApiComponentsReferenced;
+    'x-tagGroups'?: {
+        name: string;
+        tags: string[];
+    }[];
+};
+export type AsyncApiInfo = {
+    title: string;
+    version: string;
+    description?: string | Node[] | Node;
+    termsOfService?: string;
+    contact?: AsyncApiContact;
+    license?: AsyncApiLicense;
+    tags?: AsyncApiTag[];
+    externalDocs?: AsyncApiExternalDocs;
+};
+export type AsyncApiContact = {
+    name?: string;
+    url?: string;
+    email?: string;
+};
+export type AsyncApiLicense = {
+    name: string;
+    url?: string;
+};
+export type AsyncApiTag = {
+    name: string;
+    description?: string | Node[] | Node;
+    externalDocs?: AsyncApiExternalDocs;
+};
+export type AsyncApiExternalDocs = {
+    description?: string | Node[] | Node;
+    url: string;
+};
+export type AsyncApiServer = {
+    host: string;
+    /** AsyncAPI 2.x servers carry `url` instead of `host`. */
+    url?: string;
+    protocol: string;
+    protocolVersion?: string;
+    pathname?: string;
+    description?: string | Node[] | Node;
+    title?: string;
+    summary?: string;
+    variables?: AsyncApiServerVariables;
+    tags?: AsyncApiTag[];
+    externalDocs?: AsyncApiExternalDocs;
+    bindings?: AsyncApiServerBinding;
+};
+export type AsyncApiServerVariables = {
+    [name: string]: AsyncApiServerVariable;
+};
+export type AsyncApiChannels = {
+    [name: string]: AsyncApiChannel;
+};
+export type AsyncApiServerVariable = {
+    enum?: string[];
+    default: string;
+    description?: string | Node[] | Node;
+    examples?: string[];
+};
+export type AsyncApiServerBinding = {
+    kafka?: AsyncApiServerKafkaBinding;
+};
+export type AsyncApiServerKafkaBinding = {
+    schemaRegistryUrl?: string;
+    schemaRegistryVendor?: string;
+    bindingVersion?: string;
+};
+export type AsyncApiChannel = {
+    address?: string;
+    messages?: AsyncApiMessages;
+    title?: string;
+    summary?: string;
+    description?: string | Node[] | Node;
+    servers?: AsyncApiServer[];
+    parameters?: AsyncApiParameters;
+    tags?: AsyncApiTag[];
+    externalDocs?: AsyncApiExternalDocs;
+    bindings?: AsyncApiChannelBinding;
+    'x-badges'?: AsyncApiXBadges[];
+};
+export type AsyncApiXBadges = {
+    name: string;
+    position?: 'before' | 'after';
+    color?: string;
+};
+export type AsyncApiChannelBinding = {
+    kafka?: AsyncApiChannelKafkaBinding;
+    amqp?: AsyncApiChannelAMQPBinding;
+};
+export type AsyncApiChannelKafkaBinding = {
+    topic?: string;
+    partitions?: number;
+    replicas?: number;
+    bindingVersion?: string;
+    topicConfiguration?: {
+        'cleanup.policy'?: string[];
+        'retention.ms'?: number;
+        'retention.bytes'?: number;
+        'delete.retention.ms'?: number;
+        'max.message.bytes'?: number;
+        'confluent.key.schema.validation'?: boolean;
+        'confluent.key.subject.name.strategy'?: string;
+        'confluent.value.schema.validation'?: boolean;
+        'confluent.value.subject.name.strategy'?: string;
+    };
+};
+export type AsyncApiChannelAMQPBinding = {
+    is: 'routingKey' | 'queue';
+};
+export type AsyncApiMessages = {
+    [name: string]: AsyncApiMessage;
+};
+export type AsyncApiParameters = {
+    [name: string]: AsyncApiParameter;
+};
+export type AsyncApiParameter = {
+    enum?: string[];
+    default?: string;
+    description?: string | Node[] | Node;
+    examples?: string[];
+    location?: string;
+};
+export type AsyncApiMessage = {
+    headers?: AsyncAPISchema;
+    payload?: AsyncAPISchema;
+    correlationId?: AsyncApiCorrelationId;
+    contentType?: string;
+    name?: string;
+    title?: string;
+    summary?: string;
+    description?: string | Node[] | Node;
+    tags?: AsyncApiTag[];
+    externalDocs?: AsyncApiExternalDocs;
+    bindings?: AsyncApiMessageBinding;
+    examples?: AsyncApiMessageExample[];
+};
+export type AsyncApiMessageReferenced = {
+    headers?: AsyncAPISchema;
+    payload?: Referenced<AsyncAPISchema>;
+    correlationId?: AsyncApiCorrelationId;
+    contentType?: string;
+    name?: string;
+    title?: string;
+    summary?: string;
+    description?: string | Node[] | Node;
+    tags?: AsyncApiTag[];
+    externalDocs?: AsyncApiExternalDocs;
+    bindings?: AsyncApiMessageBinding;
+    examples?: AsyncApiMessageExample[];
+};
+export type AsyncApiCorrelationId = {
+    description?: string | Node[] | Node;
+    location: string;
+};
+export type AsyncApiMessageBinding = {
+    kafka?: AsyncApiMessageKafkaBinding;
+};
+export type AsyncApiMessageKafkaBinding = {
+    key?: JSONSchema7;
+    schemaIdLocation?: string;
+    schemaIdPayloadEncoding?: string;
+    schemaLookupStrategy?: string;
+    bindingVersion?: string;
+};
+export type AsyncApiMessageExample = {
+    payload?: Record<string, unknown>;
+    name?: string;
+    summary?: string;
+};
+export type MultiFormatSchemaObject = {
+    schema: JSONSchema7 | AvroSchema;
+    schemaFormat: string;
+};
+export type AsyncApiOperations = {
+    [name: string]: AsyncApiOperation;
+};
+export type AsyncApiOperationsReferenced = {
+    [name: string]: AsyncApiOperationReferenced;
+};
+export type AsyncApiOperation = {
+    action: 'send' | 'receive';
+    channel: AsyncApiChannel;
+    title?: string;
+    summary?: string;
+    description?: string | Node[] | Node;
+    tags?: AsyncApiTag[];
+    externalDocs?: AsyncApiExternalDocs;
+    bindings?: AsyncApiOperationBinding;
+    traits?: AsyncApiOperationTraits[];
+    messages?: AsyncApiMessage[];
+    reply?: AsyncApiOperationReply;
+    'x-badges'?: AsyncApiXBadges[];
+};
+export type AsyncApiOperationReferenced = {
+    action: 'send' | 'receive';
+    channel: AsyncApiChannel;
+    title?: string;
+    summary?: string;
+    description?: string | Node[] | Node;
+    tags?: AsyncApiTag[];
+    externalDocs?: AsyncApiExternalDocs;
+    bindings?: AsyncApiOperationBinding;
+    traits?: AsyncApiOperationTraits[];
+    messages?: Referenced<AsyncApiMessage>[];
+    reply?: AsyncApiOperationReply;
+    'x-badges'?: AsyncApiXBadges[];
+};
+export type AsyncApiOperationReply = {
+    address?: {
+        description?: string | Node[] | Node;
+        location: string;
+    };
+    channel?: AsyncApiChannel;
+    messages?: AsyncApiMessage[];
+};
+export type AsyncApiOperationTraits = {
+    title?: string;
+    summary?: string;
+    description?: string | Node[] | Node;
+    tags?: AsyncApiTag[];
+    externalDocs?: AsyncApiExternalDocs;
+    bindings?: AsyncApiOperationBinding;
+};
+export type AsyncApiOperationBinding = {
+    kafka?: AsyncApiOperationKafkaBinding;
+};
+export type AsyncApiOperationKafkaBinding = {
+    groupId?: {
+        type: string;
+        enum: string[];
+    };
+    clientId?: {
+        type: string;
+        enum: string[];
+    };
+    bindingVersion?: string;
+};
+export type AsyncApiComponents = {
+    messages: Record<string, AsyncApiMessage>;
+    schemas: Record<string, AsyncAPISchema>;
+    tags: Record<string, AsyncApiTag>;
+};
+export type AsyncApiComponentsReferenced = {
+    messages: Record<string, AsyncApiMessageReferenced>;
+    schemas: Record<string, AsyncAPISchema>;
+    tags: Record<string, AsyncApiTag>;
+};
+export type AvroSchema = {
+    type: string | string[] | AvroSchema[];
+    name?: string;
+    doc?: string;
+    symbols?: string[];
+    fields?: Array<{
+        name: string;
+        type: AvroSchema | string | (string | AvroSchema)[];
+        doc?: string;
+        default?: unknown;
+    }>;
+    items?: AvroSchema | string;
+    values?: AvroSchema | string;
+};
+export type ResolvedAsyncApiNavItem = ResolvedNavItem & {
+    items?: ResolvedAsyncApiNavItem[];
+    action?: string;
+    ast?: Node | Node[];
+    httpVerb?: string;
+};
+export type DownloadUrls = {
+    url: string;
+};
+export type ChannelWithKey = AsyncApiChannel & {
+    key: string;
+};
+export type AsyncAPISchema = JSONSchema7 | MultiFormatSchemaObject;
+export declare const CONST_PROTOCOL_VARIANT: {
+    readonly DEFAULT: 'default';
+    readonly KAFKA: 'kafka';
+    readonly AMQP: 'amqp';
+    readonly WSS: 'wss';
+};
+export type ProtocolVariant = ObjectValues<typeof CONST_PROTOCOL_VARIANT>;
+export type AsyncApiBuildContext = {
+    document: AsyncApiDefinition;
+    options: ApiDocsOptions;
+    basePath: string;
+    storeCtx: StoreContext;
+    protocol: ProtocolVariant | null;
+    channelToOperations: Record<string, string[]>;
+    groups: Record<string, ApiItem[]>;
+    items: ApiItem[];
+    descriptionItems: ApiItem[];
+    channelSummaries: Map<string, string>;
+    processContent: boolean;
+};
+export type BrokerData = {
+    /** Server host (3.x `host`, 2.x `url`); absent only for invalid documents. */
+    url?: string;
+    description?: string | Node[] | Node;
+    name?: string;
+    variables?: Record<string, {
+        enum?: string[];
+        default: string;
+        description?: string | Node[] | Node;
+        examples?: string[];
+    }>;
+    protocol?: string;
+    protocolVersion?: string;
+    pathname?: string;
+    title?: string;
+    summary?: string;
+    tags?: AsyncApiTag[];
+    externalDocs?: AsyncApiExternalDocs;
+    bindings?: AsyncApiServerBinding;
+};
+export type AsyncApiContext = {
+    protocol: string | null;
+};

package/typings/types/code-samples-config.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Community edition: generated code samples are not included. The language
+ * list survives only to drive the payload tab and `x-codeSamples` matching.
+ * `key` and `label` are stamped onto every entry by `normalizeCodeSamples()`.
+ */
+export interface CodeSamplesConfig {
+    languages: {
+        lang: string;
+        label: string;
+        key: string;
+    }[];
+}

package/typings/types/common.d.ts

@@ -0,0 +1,162 @@
+import type { Node } from '@markdoc/markdoc';
+import type { ConfigureRequestValues, ConfigureServerRequestValues } from '@redocly/theme/ext/configure';
+export type { ConfigureRequestValues, ConfigureServerRequestValues };
+export type ObjectValues<T> = T[keyof T];
+export type OpenAPIRef = {
+    $ref: string;
+    'x-refsStack'?: string[];
+    summary?: string;
+    description?: string | Node[] | Node;
+};
+export type Referenced<T> = T | OpenAPIRef;
+export type SeoData = {
+    title?: string;
+    description?: string;
+    keywords?: string;
+    image?: string;
+};
+export type ExternalDocsData = {
+    url: string;
+    description?: string | Node[] | Node;
+};
+export type BadgeData = {
+    name: string;
+    color?: string;
+    position?: 'before' | 'after';
+    icon?: string;
+    description?: string;
+};
+export type Badge = {
+    name: string;
+    color?: string;
+    icon?: string;
+    description?: string;
+};
+export type ServerData = {
+    url: string;
+    name?: string;
+    description?: string;
+    variables?: Record<string, {
+        enum?: string[];
+        default: string;
+        description?: string | Node[] | Node;
+        examples?: string[];
+    }>;
+};
+export declare const apiSpecType: {
+    readonly OPENAPI: 'openapi';
+    readonly ASYNCAPI: 'asyncapi';
+    readonly GRAPHQL: 'graphql';
+};
+export type ApiSpecType = ObjectValues<typeof apiSpecType>;
+export declare const tagKind: {
+    readonly NAV: 'nav';
+    readonly BADGE: 'badge';
+    readonly AUDIENCE: 'audience';
+};
+export type TagKind = ObjectValues<typeof tagKind>;
+export declare const contentType: {
+    readonly OVERVIEW: 'overview';
+    readonly GROUP: 'group';
+    readonly ITEM: 'item';
+};
+export type ContentType = ObjectValues<typeof contentType>;
+export declare const itemVariant: {
+    readonly HTTP_ITEM: 'httpItem';
+    readonly SCHEMA: 'schema';
+    readonly CHANNEL: 'channel';
+    readonly CHANNEL_OPERATION: 'channelOperation';
+    readonly MESSAGE: 'message';
+    readonly QUERY: 'query';
+    readonly MUTATION: 'mutation';
+    readonly SUBSCRIPTION: 'subscription';
+    readonly DIRECTIVE: 'directive';
+    readonly OBJECT: 'object';
+    readonly INTERFACE: 'interface';
+    readonly INPUT: 'input';
+    readonly UNION: 'union';
+    readonly ENUM: 'enum';
+    readonly SCALAR: 'scalar';
+    readonly MARKDOWN: 'markdown';
+};
+export type ItemVariant = ObjectValues<typeof itemVariant>;
+export declare const securitySchemeType: {
+    readonly API_KEY: 'apiKey';
+    readonly HTTP: 'http';
+    readonly OAUTH2: 'oauth2';
+    readonly OPEN_ID_CONNECT: 'openIdConnect';
+    readonly MUTUAL_TLS: 'mutualTLS';
+};
+export type SecuritySchemeType = ObjectValues<typeof securitySchemeType>;
+export declare const securitySchemeIn: {
+    readonly QUERY: 'query';
+    readonly HEADER: 'header';
+    readonly COOKIE: 'cookie';
+    readonly QUERYSTRING: 'querystring';
+};
+export type SecuritySchemeIn = ObjectValues<typeof securitySchemeIn>;
+export declare const nodeTypes: {
+    readonly CONTAINER: 'container';
+    readonly HEADER: 'header';
+    readonly EMPTY_MESSAGE: 'empty-message';
+    readonly ITEM: 'item-content';
+    readonly SECURITY: 'security';
+    readonly MARKDOC: 'markdoc';
+    readonly ADMONITION: 'admonition';
+    readonly OVERVIEW_SECTION_WRAPPER: 'overview-section-wrapper';
+    readonly EXTERNAL_DOCS: 'external-docs';
+    readonly CHANNEL_ADDRESS: 'channel-address';
+    readonly MESSAGE_LINKS: 'message-links';
+    readonly INFO_METADATA: 'info-metadata';
+    readonly EXTENSIONS: 'extensions';
+};
+export type NodeTypes = ObjectValues<typeof nodeTypes>;
+export declare const panelKind: {
+    readonly LOCATIONS: 'locations';
+    readonly GROUP_ITEMS: 'group-items';
+    readonly EXTERNAL_LINK: 'externallink';
+    readonly EMAIL: 'email';
+    readonly PAYLOAD: 'payload';
+    readonly TAGS: 'tags';
+    readonly CONNECT_MCP_BUTTON: 'connect-mcp-button';
+    readonly ATTRIBUTE: 'attribute';
+    readonly DOWNLOAD: 'download';
+    readonly SERVERS: 'servers';
+    readonly BROKERS: 'brokers';
+    readonly CHANNEL_BINDING: 'channel-binding';
+    readonly OPERATION_BINDING: 'operation-binding';
+    readonly MESSAGE_BINDING: 'message-binding';
+    readonly MESSAGE_REFERENCES: 'message-references';
+    readonly REFERENCES: 'references';
+    readonly CODE_SAMPLE: 'code-sample';
+    readonly CALLBACK_PAYLOAD: 'callback-payload';
+    readonly RESPONSE: 'response';
+    readonly GRAPHQL_QUERY: 'graphql-query';
+    readonly GRAPHQL_RESPONSE: 'graphql-response';
+    readonly GRAPHQL_VARIABLES: 'graphql-variables';
+    readonly GRAPHQL_TYPE_SAMPLE: 'graphql-type-sample';
+    readonly MCP_EXAMPLE: 'mcp-example';
+};
+export type PanelKind = ObjectValues<typeof panelKind>;
+export declare const schemaKind: {
+    readonly JSON_SCHEMA: 'json-schema';
+    readonly GRAPHQL_TYPE: 'graphql-type';
+};
+export type SchemaKind = ObjectValues<typeof schemaKind>;
+/** A logo as authored, keyed by `url`: OpenAPI `info.x-logo` and the standalone `logo` prop. */
+export type RawLogo = {
+    url?: string;
+    href?: string;
+    altText?: string;
+    backgroundColor?: string;
+};
+/**
+ * A logo normalized to what the `SidebarLogo` component renders, keyed by `imageUrl`.
+ * Also the shape of the `apiLogo` option, which is authored this way already.
+ */
+export type SidebarLogo = {
+    imageUrl?: string;
+    href?: string;
+    altText?: string;
+    backgroundColor?: string;
+};