如何在Stoplight Elements文档概览页末尾添加自定义流程图？

一、React自动生成流程图（可行） #

完全可以通过React生态的流程图库自动生成，无需手动制作图片，后续维护和修改更灵活，推荐两种实用方案：

1. 使用react-flow（自定义交互式流程图） #

• 先安装依赖：

  npm install reactflow
  

• 在API文档页面组件中，定义流程图的节点和边，将其渲染在Stoplight Elements的概览区域之后：

  import React from 'react';
  import { Elements } from '@stoplight/elements/react';
  import '@stoplight/elements/styles.min.css';
  import { ReactFlowProvider, ReactFlow, Controls } from 'reactflow';
  import 'reactflow/dist/style.css';
  
  const nodes = [
    { id: '1', position: { x: 0, y: 0 }, data: { label: '用户发起API请求' } },
    { id: '2', position: { x: 200, y: 0 }, data: { label: '后端验证权限' } },
    { id: '3', position: { x: 400, y: 0 }, data: { label: '返回响应数据' } },
  ];
  
  const edges = [
    { id: 'e1-2', source: '1', target: '2' },
    { id: 'e2-3', source: '2', target: '3' },
  ];
  
  export default function APIDocPage() {
    return (
      <div>
        <Elements
          apiDescriptionUrl="/openapi.json"
          router="hash"
        />
        {/* 在概览页末尾添加自动生成的流程图 */}
        <div style={{ marginTop: '40px', padding: '0 20px' }}>
          <h3>API调用流程</h3>
          <ReactFlowProvider>
            <ReactFlow nodes={nodes} edges={edges} fitView>
              <Controls />
            </ReactFlow>
          </ReactFlowProvider>
        </div>
      </div>
    );
  }
  

2. 使用mermaid-react（基于文本语法生成流程图） #

如果流程图逻辑能用Mermaid语法描述，这种方式更简洁：

• 安装依赖：

  npm install @mermaid-js/mermaid-react
  

• 在组件中实现：

  import React from 'react';
  import { Elements } from '@stoplight/elements/react';
  import '@stoplight/elements/styles.min.css';
  import { Mermaid } from '@mermaid-js/mermaid-react';
  
  export default function APIDocPage() {
    const flowChartCode = `
      graph LR
      A[用户发起请求] --> B[权限验证]
      B --> C{验证通过?}
      C -->|是| D[返回数据]
      C -->|否| E[返回错误]
    `;
  
    return (
      <div>
        <Elements
          apiDescriptionUrl="/openapi.json"
          router="hash"
        />
        <div style={{ marginTop: '40px', padding: '0 20px' }}>
          <h3>API调用流程</h3>
          <Mermaid chart={flowChartCode} />
        </div>
      </div>
    );
  }
  

二、插入静态图片实现（备选方案） #

如果不想用代码生成，直接插入图片的步骤如下：

1. 将制作好的流程图导出为PNG/SVG格式，放到项目的public目录，或上传到静态资源服务器。
2. 在React组件中，在Stoplight Elements组件之后添加图片标签：

   import React from 'react';
   import { Elements } from '@stoplight/elements/react';
   import '@stoplight/elements/styles.min.css';
   // 若图片放在src目录，可通过import导入
   // import FlowChart from './assets/api-flow-chart.png';
   
   export default function APIDocPage() {
     return (
       <div>
         <Elements
           apiDescriptionUrl="/openapi.json"
           router="hash"
         />
         <div style={{ marginTop: '40px', padding: '0 20px', textAlign: 'center' }}>
           <h3>API调用流程</h3>
           {/* 方式1：引用public目录下的图片 */}
           <img src="/api-flow-chart.png" alt="API调用流程图" style={{ maxWidth: '100%', height: 'auto' }} />
           {/* 方式2：使用import导入的图片 */}
           {/* <img src={FlowChart} alt="API调用流程图" style={{ maxWidth: '100%', height: 'auto' }} /> */}
         </div>
       </div>
     );
   }
   

3. 通过style属性调整图片宽度、边距等样式，确保和页面风格匹配。

注意：如果Stoplight Elements提供自定义概览内容的插槽（如overviewContent props），优先用官方扩展方式插入，避免破坏原有布局。

内容的提问来源于stack exchange，提问作者Light Yagami