> 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.

# @rspress/plugin-api-docgen 

[Исходный код](https://github.com/web-infra-dev/rspress/tree/main/packages/plugin-api-docgen)

Этот плагин автоматически генерирует контент документации API, используя пакеты [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript) и [documentation](https://github.com/documentationjs/documentation).

## Установка


```sh [npm]
npm add @rspress/plugin-api-docgen -D
```

```sh [yarn]
yarn add @rspress/plugin-api-docgen -D
```

```sh [pnpm]
pnpm add @rspress/plugin-api-docgen -D
```

```sh [bun]
bun add @rspress/plugin-api-docgen -D
```

```sh [deno]
deno add npm:@rspress/plugin-api-docgen -D
```

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

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

```ts
// 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:

```mdx
## API

Таблица API

<API moduleName="button" />
```

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

Этот плагин использует [API плагинов `i18nSource`](/rspress-russian/plugin/system/plugin-api.md#i18nsource), чтобы добавить следующие переводы:


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

Источник: [packages/plugin-api-docgen/static/i18n.ts](https://github.com/web-infra-dev/rspress/blob/main/packages/plugin-api-docgen/static/i18n.ts)
```ts title="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`](/rspress-russian/api/config/config-basic.md#i18nsource).

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

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

```ts
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` используется для сценариев библиотек компонентов. Он парсит пропсы для генерации таблиц.

```tsx
export type ButtonProps = {
  /**
   * Отключена ли кнопка?
   */
  disabled?: boolean;
  /**
   * Тип кнопки
   * @default 'default'
   */
  size?: 'mini' | 'small' | 'default' | 'large';
};
export const Button = (props?: ButtonProps) => {};
```

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

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

```tsx
const A = () => {};

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

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

```mdx
### ButtonTest

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

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

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

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

```tsx
import { FC } from 'react';
```

:::

- `documentation` используется в сценариях утилитарных библиотек для парсинга аннотаций JSDoc.
  Вот функция `greet` с аннотациями JSDoc.

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

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

```md
<!-- 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` передает параметры выбранному парсеру. Его тип:

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

Смотрите [ParserOptions](https://github.com/styleguidist/react-docgen-typescript/blob/b7ea0a235efb7c78a1158ca12d864de2bc2ee30e/src/parser.ts#L84-L95) и [DocumentationArgs](https://github.com/documentationjs/documentation/blob/master/docs/NODE_API.md#parameters-1) для доступных параметров.

Когда парсер — `react-docgen-typescript`, `withDefaultConfig` по умолчанию создает экземпляр парсера. Если настроены `tsconfigPath` или `compilerOptions`, их можно задать отдельно для каждой `entry`; `withCompilerOptions` и `withCustomConfig` используются для создания экземпляра парсера соответственно. Подробности смотрите в [Custom Parsers](https://github.com/styleguidist/react-docgen-typescript/blob/b7ea0a235efb7c78a1158ca12d864de2bc2ee30e/README.md#usage).
