EchoAPI OpenAPI Doc

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

安装

使用 yarn 安装：

yarn add echoapi-openapi-doc

使用方式

1. 引入组件和样式

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

2. 使用组件

<OpenApiDoc
  spec={spec}
  language={language}
  theme={theme}
  themeOptions={{
    themeColor: '#835DFF',
    themeHoverColor: 'rgba(131, 93, 255, 0.05)'
  }}
  targetKey={query_target_id || ''}
  onActiveChange={onActiveChange}
/>

参数说明

interface Props {
  /**
   * OpenAPI 3.0 及以上版本的规范
   */
  spec: OpenAPI.OpenAPI31Spec;

  /**
   * 主题模式，默认为 'light'
   */
  theme?: 'light' | 'dark';

  /**
   * 主题自定义选项
   */
  themeOptions?: Theme | {};

  /**
   * 文档语言，默认为 'zh-CN'
   */
  language?: LANGUAGE_TYPE;

  /**
   * 目标键值，用于定位文档中的特定部分
   */
  targetKey?: string;

  /**
   * 当文档中的活动部分发生变化时的回调函数
   */
  onActiveChange?: any;

  /**
   * 布局选项
   */
  options?: {
    hideCrumbs?: boolean; // 隐藏面包屑
    hideSideBar?: boolean; // 隐藏左侧目录
    hideMeowPointList?: boolean; // 隐藏右侧喵点
    hideFooter?: boolean; // 隐藏底部切换
    defaultPackUpSideBar?: boolean; // 默认收起左侧目录
  };
}

主要功能

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

示例

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

const spec = {
  openapi: '3.0.0',
  info: {
    title: 'Sample API',
    version: '1.0.0',
  },
  paths: {
    '/example': {
      get: {
        summary: 'Get example data',
        responses: {
          '200': {
            description: 'Successful response',
          },
        },
      },
    },
  },
};

function App() {
  return (
    <OpenApiDoc
      spec={spec}
      theme="dark"
      themeOptions={{
        themeColor: '#835DFF',
        themeHoverColor: 'rgba(131, 93, 255, 0.05)',
      }}
      options={{
        hideFooter: true,
        defaultPackUpSideBar: true,
      }}
    />
  );
}

export default App;