docusaurus-theme-openapi-docs/src/types.ts

OpenAPI theme for Docusaurus.

/* ============================================================================
 * Copyright (c) Palo Alto Networks
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 * ========================================================================== */

import type { FrontMatterTag } from "@docusaurus/utils";
import type { JSONSchema4, JSONSchema6, JSONSchema7 } from "json-schema";

export interface ThemeConfig {
  api?: {
    proxy?: string;
    authPersistance?: false | "localStorage" | "sessionStorage";
  };
}

interface Map<T> {
  [key: string]: T;
}

export type JSONSchema = JSONSchema4 | JSONSchema6 | JSONSchema7;
export type SchemaObject = Omit<
  JSONSchema,
  | "type"
  | "allOf"
  | "oneOf"
  | "anyOf"
  | "not"
  | "items"
  | "properties"
  | "additionalProperties"
> & {
  // OpenAPI specific overrides
  type?: "string" | "number" | "integer" | "boolean" | "object" | "array";
  allOf?: SchemaObject[];
  oneOf?: SchemaObject[];
  anyOf?: SchemaObject[];
  not?: SchemaObject;
  items?: SchemaObject;
  properties?: Map<SchemaObject>;
  additionalProperties?: boolean | SchemaObject;

  // OpenAPI additions
  nullable?: boolean;
  discriminator?: DiscriminatorObject;
  readOnly?: boolean;
  writeOnly?: boolean;
  xml?: XMLObject;
  externalDocs?: ExternalDocumentationObject;
  example?: any;
  deprecated?: boolean;
};

export interface DiscriminatorObject {
  propertyName: string;
  mapping?: Map<string>;
}

export interface XMLObject {
  name?: string;
  namespace?: string;
  prefix?: string;
  attribute?: boolean;
  wrapped?: boolean;
}

export interface ExternalDocumentationObject {
  description?: string;
  url: string;
}

export type FileChange = {
  author?: string;
  /** Date can be any
   * [parsable date string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse).
   */
  date?: Date | string;
};

export type DocFrontMatter = {
  /**
   * The last part of the doc ID (will be refactored in the future to be the
   * full ID instead)
   * @see {@link DocMetadata.id}
   */
  id?: string;
  /**
   * Will override the default title collected from h1 heading.
   * @see {@link DocMetadata.title}
   */
  title?: string;
  /**
   * Front matter tags, unnormalized.
   * @see {@link DocMetadata.tags}
   */
  tags?: FrontMatterTag[];
  /**
   * If there isn't a Markdown h1 heading (which, if there is, we don't
   * remove), this front matter will cause the front matter title to not be
   * displayed in the doc page.
   */
  hide_title?: boolean;
  /** Hide the TOC on the right. */
  hide_table_of_contents?: boolean;
  /** Used in the head meta. */
  keywords?: string[];
  /** Used in the head meta. Should use `assets.image` in priority. */
  image?: string;
  /**
   * Will override the default excerpt.
   * @see {@link DocMetadata.description}
   */
  description?: string;
  /**
   * Custom slug appended after /<baseUrl>/<routeBasePath>/<versionPath>
   * @see {@link DocMetadata.slug}
   */
  slug?: string;
  /** Customizes the sidebar label for this doc. Will default to its title. */
  sidebar_label?: string;
  /**
   * Controls the position of a doc inside the generated sidebar slice when
   * using autogenerated sidebar items.
   *
   * @see https://docusaurus.io/docs/sidebar#autogenerated-sidebar-metadata
   */
  sidebar_position?: number;
  /**
   * Gives the corresponding sidebar label a special class name when using
   * autogenerated sidebars.
   */
  sidebar_class_name?: string;
  /**
   * Will be propagated to the final sidebars data structure. Useful if you
   * have swizzled sidebar-related code or simply querying doc data through
   * sidebars.
   */
  sidebar_custom_props?: { [key: string]: unknown };
  /**
   * Changes the sidebar association of the current doc. Use `null` to make
   * the current doc not associated to any sidebar.
   */
  displayed_sidebar?: string | null;
  /**
   * Customizes the pagination label for this doc. Will default to the sidebar
   * label.
   */
  pagination_label?: string;
  /** Overrides the default URL computed for this doc. */
  custom_edit_url?: string | null;
  /**
   * Whether number prefix parsing is disabled on this doc.
   * @see https://docusaurus.io/docs/sidebar#using-number-prefixes
   */
  parse_number_prefixes?: boolean;
  /**
   * Minimum TOC heading level. Must be between 2 and 6 and lower or equal to
   * the max value.
   */
  toc_min_heading_level?: number;
  /** Maximum TOC heading level. Must be between 2 and 6. */
  toc_max_heading_level?: number;
  /**
   * The ID of the documentation you want the "Next" pagination to link to.
   * Use `null` to disable showing "Next" for this page.
   * @see {@link DocMetadata.next}
   */
  pagination_next?: string | null;
  /**
   * The ID of the documentation you want the "Previous" pagination to link
   * to. Use `null` to disable showing "Previous" for this page.
   * @see {@link DocMetadata.prev}
   */
  pagination_prev?: string | null;
  /** Should this doc be excluded from production builds? */
  draft?: boolean;
  /** Allows overriding the last updated author and/or date. */
  last_update?: FileChange;
  /** Provides OpenAPI Docs with a reference path to their respective Info Doc */
  info_path?: string;
};