EchoAPI OpenAPI Doc

echoapi-openapi-doc 是一个用于生成 OpenAPI 3.0 及以上版本文档的 React 组件库。通过传入 OpenAPI 规范的 spec，它可以自动生成美观且交互友好的 API 文档 UI，支持自定义主题、语言和布局选项。

---

安装

使用 yarn 安装：

1yarn add echoapi-openapi-doc

使用方式

1. 引入组件和样式

1import { OpenApiDoc } from 'echoapi-openapi-doc';
2import 'echoapi-openapi-doc/styles/index.esm.css';

2. 使用组件

1<OpenApiDoc
2  spec={spec}
3  language={language}
4  theme={theme}
5  themeOptions={{
6    themeColor: '#835DFF',
7    themeHoverColor: 'rgba(131, 93, 255, 0.05)'
8  }}
9  targetKey={query_target_id || ''}
10  onActiveChange={onActiveChange}
11/>

参数说明

1interface Props {
2  /**
3   * OpenAPI 3.0 及以上版本的规范
4   */
5  spec: OpenAPI.OpenAPI31Spec;
6
7  /**
8   * 主题模式，默认为 'light'
9   */
10  theme?: 'light' | 'dark';
11
12  /**
13   * 主题自定义选项
14   */
15  themeOptions?: Theme | {};
16
17  /**
18   * 文档语言，默认为 'zh-CN'
19   */
20  language?: LANGUAGE_TYPE;
21
22  /**
23   * 目标键值，用于定位文档中的特定部分
24   */
25  targetKey?: string;
26
27  /**
28   * 当文档中的活动部分发生变化时的回调函数
29   */
30  onActiveChange?: any;
31
32  /**
33   * 布局选项
34   */
35  options?: {
36    hideCrumbs?: boolean; // 隐藏面包屑
37    hideSideBar?: boolean; // 隐藏左侧目录
38    hideMeowPointList?: boolean; // 隐藏右侧喵点
39    hideFooter?: boolean; // 隐藏底部切换
40    defaultPackUpSideBar?: boolean; // 默认收起左侧目录
41  };
42}

主要功能

• 自动生成文档：通过传入 OpenAPI 3.0 及以上版本的 spec，自动生成 API 文档 UI。
• ​主题支持：支持 light 和 dark 两种主题模式，并提供自定义主题选项。
• ​多语言支持：支持多种语言（如 zh-CN、en-US 等），默认中文。
• ​布局自定义：可以通过 options 参数隐藏或调整文档的布局组件。 ​* 交互友好：支持文档内部的快速导航、面包屑、喵点列表等功能。

示例

1import React from 'react';
2import { OpenApiDoc } from 'echoapi-openapi-doc';
3import 'echoapi-openapi-doc/styles/index.esm.css';
4
5const spec = {
6  openapi: '3.0.0',
7  info: {
8    title: 'Sample API',
9    version: '1.0.0',
10  },
11  paths: {
12    '/example': {
13      get: {
14        summary: 'Get example data',
15        responses: {
16          '200': {
17            description: 'Successful response',
18          },
19        },
20      },
21    },
22  },
23};
24
25function App() {
26  return (
27    <OpenApiDoc
28      spec={spec}
29      theme="dark"
30      themeOptions={{
31        themeColor: '#835DFF',
32        themeHoverColor: 'rgba(131, 93, 255, 0.05)',
33      }}
34      options={{
35        hideFooter: true,
36        defaultPackUpSideBar: true,
37      }}
38    />
39  );
40}
41
42export default App;