> For AI agents: the complete documentation index is available at https://rspress.rs/llms.txt, the full documentation bundle is available at https://rspress.rs/llms-full.txt.

# @rspress/plugin-api-docgen 

[Source Code](https://github.com/web-infra-dev/rspress/tree/main/packages/plugin-api-docgen)

This plugin generates API reference content automatically, powered by [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript) and [documentation](https://github.com/documentationjs/documentation).

## Install


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

## Usage

First, add the following configuration:

```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',
    }),
  ],
});
```

Then use the `API` component to inject API documentation into an MDX file:

```mdx
## API

This is API Table

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

## Config

The plugin accepts an object with the following type:

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

### appDir

`appDir` configures the base directory for parsing. The default is `process.cwd()`.

### entries

`entries` configures the files to parse.

- The key is an identifier used as the `moduleName` attribute of the `API` component.
- The value is the relative path to the file being parsed.

### apiParseTool

`apiParseTool` selects the parser. The default is `react-docgen-typescript`:

- `react-docgen-typescript` is used for component library scenarios. It parses props to generate tables.

```tsx
export type ButtonProps = {
  /**
   * Whether to disable the button
   */
  disabled?: boolean;
  /**
   * Type of Button
   * @default 'default'
   */
  size?: 'mini' | 'small' | 'default' | 'large';
};
export const Button = (props?: ButtonProps) => {};
```

In this standard form, `ButtonProps` is extracted into a table and `Button` is used as the table title.
If you use a default export, the file name is used as the table title.

Note that exports declared elsewhere are not available.

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

export { A }; // wrong
export default A; // wrong
export const B = () => {}; // right
export default () => {}; // right
```

The generated content is as follows:

```mdx
### ButtonTest

|  Props   |          Description          |                    Type                     |   Default   |
| :------: | :---------------------------: | :-----------------------------------------: | :---------: |
| disabled | Whether to disable the button |                  `boolean`                  |     `-`     |
|   size   |        Type of Button         | `"mini" \| "small" \| "default" \| "large"` | `'default'` |
```

:::warning
If props use React types, add those types in `tsconfig.json`; otherwise, types under the React namespace cannot be resolved.

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

The best approach is to import the type directly:

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

:::

- `documentation` is used in utility library scenarios to parse JSDoc annotations.
  Here is a `greet` function with JSDoc annotations.

```ts
/**
 * Greet function that returns a greeting message.
 * @param {string} name - The name of the person to greet.
 * @param {string} [greeting='Hello'] - The greeting to use.
 * @returns {string} The greeting message.
 */
function greet(name: string, greeting = 'Hello') {
  return `${greeting}, ${name}!`;
}
```

The generated content is as follows:

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

## greet

Greet function that returns a greeting message.

### Parameters

- `name` **[string][1]** The name of the person to greet.
- `greeting` **[string][1]** The greeting to use. (optional, default `'Hello'`)

Returns **[string][1]** The greeting message.

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

### parseToolOptions

`parseToolOptions` passes options to the selected parser. Its type is:

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

See [ParserOptions](https://github.com/styleguidist/react-docgen-typescript/blob/b7ea0a235efb7c78a1158ca12d864de2bc2ee30e/src/parser.ts#L84-L95) and [DocumentationArgs](https://github.com/documentationjs/documentation/blob/master/docs/NODE_API.md#parameters-1) for available options.

When the parser is `react-docgen-typescript`, `withDefaultConfig` creates the parser instance by default. If `tsconfigPath` or `compilerOptions` is configured, they can be set separately for each `entry`; `withCompilerOptions` and `withCustomConfig` are used to create the parser instance respectively. See [Custom Parsers](https://github.com/styleguidist/react-docgen-typescript/blob/b7ea0a235efb7c78a1158ca12d864de2bc2ee30e/README.md#usage) for details.