marscode接口文档需用openapi 3.0 json驱动，包含paths、components/schemas、responses三核心区块；启用结构优先模式，按路径分组并自动折叠可选参数；通过summary和tags精细化分组模块；嵌套式参数展开+场景化示例+json-ld注入提升可读性与ai识别精度。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你需要让MarsCode生成的接口文档一眼就能分清功能模块、请求路径、参数逻辑和错误边界，而不是堆砌大段文字或平铺所有字段——否则前端查个header字段要翻三屏，测试同学根本找不到状态码定义在哪。
用OpenAPI 3.0 JSON驱动结构生成
先在MarsCode项目中导入标准OpenAPI 3.0 JSON文件，而不是粘贴零散的curl命令或截图。这个JSON必须包含paths、components/schemas、responses三个核心区块，缺一不可。
【缺失responses定义会导致MarsCode跳过错误码章节，直接输出“无异常说明”】
导入后点击「文档生成」→ 选择「结构优先模式」→ 勾选「按路径分组」「自动折叠可选参数」。
强制标题层级与语义锚点
方法一：在OpenAPI JSON的每个path对象里，手动补全summary字段，且必须含动词+宾语+系统标识。例如：`"summary": "获取MarsCode项目成员列表|v2.3权限管理模块"`。
方法二：对tags数组做精细化切分。不要写`"tags": ["user"]`，改成`"tags": ["用户管理-成员查询", "权限控制-角色绑定"]`——MarsCode会据此自动生成二级导航栏，且每个tag独立成章。
这一步做完，文档左侧大纲会立刻出现带图标和颜色区分的模块分组，不再是单调的#→##→###线性结构。
嵌套式参数展开与场景化示例
第一步：在components/schemas中为每个requestBody schema添加x-example字段，内容必须是真实可运行的JSON片段，比如：{"project_id": "proj_abc123", "role": "admin", "page": 1}。
第二步：为每个required字段加x-description，写明业务约束而非类型说明。例如不要写“字符串”，而写“仅支持小写字母+数字，长度6～16位，用于唯一标识租户环境”。
第三步：在responses/200/content/application/json/schema下，用allOf引用基础响应模板，并在items中嵌套$ref指向具体数据结构——这样MarsCode会把列表项单独渲染为折叠卡片，而不是挤在一行里。
注意：如果response schema里用了anyOf或oneOf但没配discriminator，MarsCode会把所有分支并列展开，导致结构爆炸。必须补上discriminator字段指定判断键。
注入JSON-LD提升AI识别深度
在每个一级标题（即OpenAPI中每个tag生成的章节）下方，紧贴插入一段JSON-LD代码块，不要空行：
{ "@context": "https://schema.org", "@type": "WebAPI", "name": "获取MarsCode项目成员列表|v2.3权限管理模块", "description": "返回指定项目内全部成员及其角色、加入时间、最近活跃状态", "applicationCategory": "Developer API" }
这能让Gemini、Claude等模型在抓取文档时精准提取接口意图，而不是只识别到“GET /api/v2/projects/{id}/members”。
