For AI agents: the complete documentation index is available at /rspress-russian/llms.txt, the full documentation bundle is available at /rspress-russian/llms-full.txt, and this page is available as Markdown at /rspress-russian/plugin/official-plugins/api-docgen.md.
close

@rspress/plugin-api-docgen

Этот плагин автоматически генерирует контент документации API, используя пакеты react-docgen-typescript и documentation.

Установка

npm
yarn
pnpm
bun
deno
npm add @rspress/plugin-api-docgen -D

Использование

Сначала добавьте следующую конфигурацию:

// rspress.config.ts
import path from 'path';
import { defineConfig } from '@rspress/core';
import { pluginApiDocgen } from '@rspress/plugin-api-docgen';

export default defineConfig({
  plugins: [
    pluginApiDocgen({
      entries: {
        button: './src/index.ts',
      },
      apiParseTool: 'react-docgen-typescript',
    }),
  ],
});

Затем используйте компонент API для вставки документации API в файл MDX:

## API

Таблица API

<API moduleName="button" />

Интернационализация

Этот плагин использует API плагинов i18nSource, чтобы добавить следующие переводы:

Источник переводов

Источник: packages/plugin-api-docgen/static/i18n.ts

i18n.ts
// cspell:disable
export const apiDocgenI18n = {
  apiDocgenProperty: {
    en: 'Property',
    zh: '属性',
    ja: 'プロパティ',
    ko: '속성',
    ru: 'Свойство',
    ta: 'பண்பு',
  },
  apiDocgenDescription: {
    en: 'Description',
    zh: '说明',
    ja: '説明',
    ko: '설명',
    ru: 'Описание',
    ta: 'விளக்கம்',
  },
  apiDocgenType: {
    en: 'Type',
    zh: '类型',
    ja: '型',
    ko: '타입',
    ru: 'Тип',
    ta: 'வகை',
  },
  apiDocgenDefaultValue: {
    en: 'Default Value',
    zh: '默认值',
    ja: 'デフォルト値',
    ko: '기본값',
    ru: 'Значение по умолчанию',
    ta: 'இயல்புநிலை மதிப்பு',
  },
  apiDocgenRequired: {
    en: 'Required',
    zh: '必填',
    ja: '必須',
    ko: '필수',
    ru: 'Обязательно',
    ta: 'கட்டாயம்',
  },
  apiDocgenClassName: {
    en: 'Additional css class',
    zh: '节点类名',
    ja: '追加の CSS クラス',
    ko: '추가 CSS 클래스',
    ru: 'Имя класса узла',
    ta: 'கூடுதல் CSS வகுப்பு',
  },
  apiDocgenStyle: {
    en: 'Additional style',
    zh: '节点样式',
    ja: '追加のスタイル',
    ko: '추가 스타일',
    ru: 'Стиль узла',
    ta: 'பாணி',
  },
  apiDocgenChildren: {
    en: 'Children',
    zh: '子节点',
    ja: '子要素',
    ko: '자식 요소',
    ru: 'Дочерние элементы',
    ta: 'உள்ளடக்கம்',
  },
  apiDocgenDisabled: {
    en: 'Whether to disable ',
    zh: '是否禁用',
    ja: '無効にするかどうか',
    ko: '비활성화 여부',
    ru: 'Отключено',
    ta: 'முடக்க வேண்டுமா',
  },
};

Вы можете переопределить эти тексты с помощью пользовательской конфигурации i18nSource.

Конфигурация

Плагин принимает объект следующего типа:

interface Options {
  entries?: Record<string, string>;
  apiParseTool?: 'react-docgen-typescript' | 'documentation';
  appDir?: string;
  parseToolOptions?: ParseToolOptions;
}

appDir

appDir настраивает базовую директорию для парсинга. По умолчанию используется process.cwd().

entries

entries настраивает файлы для парсинга.

  • Ключ — это идентификатор, используемый как атрибут moduleName компонента API.
  • Значение — относительный путь к парсируемому файлу.

apiParseTool

apiParseTool выбирает парсер. По умолчанию используется react-docgen-typescript:

  • react-docgen-typescript используется для сценариев библиотек компонентов. Он парсит пропсы для генерации таблиц.
export type ButtonProps = {
  /**
   * Отключена ли кнопка?
   */
  disabled?: boolean;
  /**
   * Тип кнопки
   * @default 'default'
   */
  size?: 'mini' | 'small' | 'default' | 'large';
};
export const Button = (props?: ButtonProps) => {};

В этой стандартной форме ButtonProps извлекается в таблицу, а Button используется как заголовок таблицы. Если вы используете экспорт по умолчанию, в качестве заголовка таблицы используется имя файла.

Обратите внимание, что экспорты, объявленные в других местах, недоступны.

const A = () => {};

export { A }; // неправильно
export default A; // неправильно
export const B = () => {}; // правильно
export default () => {}; // правильно

Сгенерированный контент будет выглядеть следующим образом:

### ButtonTest

|   Проп   |      Описание       |                     Тип                     | Значение по умолчанию |
| :------: | :-----------------: | :-----------------------------------------: | :-------------------: |
| disabled | Отключена ли кнопка |                  `boolean`                  |          `-`          |
|   size   |    Размер кнопки    | `"mini" \| "small" \| "default" \| "large"` |      `'default'`      |
Предупреждение

Если пропсы используют типы React, добавьте эти типы в tsconfig.json; в противном случае типы в пространстве имён React не смогут быть разрешены.

{
  "compilerOptions": {
    "types": ["react"]
  }
}

Лучший подход — импортировать тип напрямую:

import { FC } from 'react';
  • documentation используется в сценариях утилитарных библиотек для парсинга аннотаций JSDoc. Вот функция greet с аннотациями JSDoc.
/**
 * Функция приветствия, возвращающая приветственное сообщение.
 * @param {string} name - Имя человека, которого нужно поприветствовать.
 * @param {string} [greeting='Привет'] - Приветствие, которое будет использовано.
 * @returns {string} Приветственное сообщение.
 */
function greet(name: string, greeting = 'Привет') {
  return `${greeting}, ${name}!`;
}

Сгенерированный контент будет выглядеть следующим образом:

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

## greet

Функция приветствия, возвращающая приветственное сообщение.

### Parameters

- `name` **[string][1]** Имя человека, которого нужно поприветствовать.
- `greeting` **[string][1]** Приветствие, которое будет использовано. (optional, default `'Hello'`)

Returns **[string][1]** Приветственное сообщение.

[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String

parseToolOptions

parseToolOptions передает параметры выбранному парсеру. Его тип:

type ParseToolOptions = {
  'react-docgen-typescript'?: ParserOptions & {
    tsconfigPath?: Record<string, string>;
    compilerOptions?: Record<string, ts.CompilerOptions>;
  };
  documentation?: DocumentationArgs;
};

Смотрите ParserOptions и DocumentationArgs для доступных параметров.

Когда парсер — react-docgen-typescript, withDefaultConfig по умолчанию создает экземпляр парсера. Если настроены tsconfigPath или compilerOptions, их можно задать отдельно для каждой entry; withCompilerOptions и withCustomConfig используются для создания экземпляра парсера соответственно. Подробности смотрите в Custom Parsers.