如何将OpenAPI响应示例转为可用于highlight.js的JSON

核心思路 #

要处理带$ref的OpenAPI响应结构，关键是递归解析所有引用，把分散的schema合并成完整的JSON对象，再传给highlight.js做语法高亮。

步骤1：加载完整OpenAPI规范 #

先把整个远程OpenAPI JSON文档加载到内存，因为$ref的引用目标（比如#/components/schemas/XXX）都在文档内部的components区域。

步骤2：递归解析$ref引用 #

写一个递归函数遍历响应结构，遇到$ref就根据路径从根文档取出对应schema替换，同时处理循环引用避免死循环：

function resolveRefs(obj, openApiDoc, visited = new Set()) {
  if (typeof obj !== 'object' || obj === null) return obj;
  
  if (obj.$ref) {
    const refPath = obj.$ref.slice(1).split('/');
    let target = openApiDoc;
    for (const part of refPath) {
      target = target[part];
      if (!target) throw new Error(`引用路径不存在：${obj.$ref}`);
    }
    if (visited.has(obj.$ref)) return target;
    visited.add(obj.$ref);
    return resolveRefs(target, openApiDoc, visited);
  }
  
  if (Array.isArray(obj)) {
    return obj.map(item => resolveRefs(item, openApiDoc, visited));
  } else {
    const resolvedObj = {};
    for (const key in obj) {
      resolvedObj[key] = resolveRefs(obj[key], openApiDoc, visited);
    }
    return resolvedObj;
  }
}

步骤3：提取并解析目标响应 #

从加载好的文档中定位到目标响应，用上面的函数解析所有引用：

// 加载远程OpenAPI规范
const openApiDoc = await fetch('你的远程规范地址').then(res => res.json());

// 定位到目标响应的schema
const targetSchema = openApiDoc.paths['/users/{id}'].get.responses['200'].content['application/json'].schema;

// 解析所有$ref引用
const resolvedSchema = resolveRefs(targetSchema, openApiDoc);

步骤4：格式化并交给highlight.js渲染 #

把解析后的结构转成格式化JSON字符串，再让highlight.js处理高亮：

// 生成带缩进的格式化JSON
const formattedJson = JSON.stringify(resolvedSchema, null, 2);

// 渲染高亮
const codeEl = document.getElementById('response-code');
codeEl.textContent = formattedJson;
hljs.highlightElement(codeEl);

额外优化 #

• 优先用响应里的examples字段（如果有），比解析schema更直接
• 可以过滤掉title、description等OpenAPI特有字段，只保留结构内容，让展示更简洁

内容的提问来源于stack exchange，提问作者Ilyas Khametov