docusaurus-theme-redoc/src/types/common.ts

Redoc Component for DocusaurusV2

import type { Props as LayoutProps } from '@theme/Layout';
import type { ObjectDescriptionProps, RedocRawOptions } from 'redoc';
import type { OpenAPISpec } from 'redoc/typings/types';

export type ParsedSpec = OpenAPISpec;

/**
 * The "SpecProps" are generated by docusaurus-plugin-redoc at build time
 * And they are passed automatically for the auto-generated pages
 */
export interface SpecProps {
  /**
   * Spec to use, already loaded previously
   */
  spec: ParsedSpec;
  /**
   * Public path to the spec file used, used by Redoc as download url
   */
  url?: string;
  /**
   * @deprecated TODO: If not spec file then pass null at build time rather than passing flags to components
   */
  isSpecFile?: boolean;
  /**
   * Theme instance to use
   */
  themeId?: string;
  /**
   * Option to disable normalization of spec download URLs
   * @deprecated TODO: Do the normalization at build time rather than in components
   */
  normalizeUrl?: boolean;
}

export interface MdxProps {
  /**
   * If you have multiple apis, then add a `id` field in the specs array
   * And pass the same here
   */
  id?: string;
  /**
   * Manually parsed JSON spec to use
   */
  spec?: ParsedSpec;
}

export interface ServerRedocProps extends SpecProps {
  className?: string;
  /**
   * Props to forward to the Redoc component
   */
  optionsOverrides?: RedocRawOptions;
}

export interface RedocProps extends Omit<ServerRedocProps, 'spec'>, MdxProps {}

export type ApiSchemaProps = Omit<
  ObjectDescriptionProps,
  'parser' | 'options' | 'schemaRef'
> &
  MdxProps & {
    /**
     * Show the example or not
     */
    example?: boolean;
    /**
     * Ref to the schema
     */
    pointer: ObjectDescriptionProps['schemaRef'];
  };

export type ApiOperationProps = MdxProps & {
  /**
   * Show the example or not
   */
  example?: boolean;

  /**
   * Ref to the operation
   */
  pointer: string;
};

export type ApiDocProps = {
  specProps: SpecProps;
  layoutProps?: Omit<LayoutProps, 'children'>;
};