Laravel中用Markdown写API文档的核心是让业务逻辑“看得见、读得懂、查得快”：通过标题层级构建语义导航，用定义列表阐明字段业务规则，以折叠区块收纳非主线说明，结合内联代码与高亮突出关键业务标识。
在 Laravel 项目中用 Markdown 写 API 文档，不只是把接口列出来，关键是让业务逻辑“看得见、读得懂、查得快”。真正的文档价值不在于语法多炫，而在于它能否降低前后端协作成本——比如一个字段为什么必填、某个状态流转的边界条件、灰度期间的兼容处理。这些内容用纯 JSON 或表格很难说清，但用 Markdown 的轻量结构就能自然承载。
用标题层级建立语义导航
API 文档不是线性阅读材料，而是供人快速跳转查阅的工具。合理使用 # 一级标题（模块）、## 二级标题（资源）、### 三级标题（具体接口）能天然生成可点击的侧边目录（尤其配合 LaRecipe 或自定义渲染器时）。更重要的是，在每个接口标题下紧接一句业务定位说明，例如：
- ### POST /api/v1/orders —— 创建新订单（支持预售与定金锁单）
- ### GET /api/v1/orders/{id} —— 查询订单详情（含履约进度与风控拦截标记）
这种写法让开发者一眼识别接口意图，无需点开再看描述字段。
用定义列表讲清字段背后的业务规则
Swagger 或 OpenAPI 的 schema 往往只定义类型和是否必填，但业务约束藏在细节里。Markdown 支持定义列表（: 语法），非常适合补充这类信息：
**status** : 订单当前状态，取值范围：`pending`（待支付）、`paid`（已支付）、`shipped`（已发货）、`cancelled`（已取消） : ⚠️ 注意：`pending` 状态下仅允许调用支付接口；`shipped` 后不可再修改收货地址 : ? 业务提示：灰度期间 `paid` 状态可能触发自动发券，详见《营销系统对接规范》
这种写法比大段文字更易扫读，也比注释块更结构化。
用折叠区块收纳非主线说明（需配合前端渲染）
有些内容重要但不常看，比如错误码映射表、幂等性实现方式、旧版兼容逻辑。原生 Markdown 不支持折叠，但可通过简单约定 + 前端 JS 实现（LaRecipe 和多数自研方案都支持）：
- 用
> [!NOTE] 幂等性说明开头的引用块，配合 JS 自动转为可展开面板 - 或统一用
<details><summary>查看完整错误码</summary>...</details>（需确保渲染器允许 HTML）
关键不是技术多酷，而是把“需要时才展开”的信息真正藏起来，避免干扰主流程阅读。
用内联代码与高亮突出关键业务标识
业务系统中常有固定字符串参与逻辑判断，比如订单来源字段 source: "miniapp"、消息类型 event: "user_registered_v2"。这些值不能只写在示例里，要明确标注其业务含义：
- 用反引号包裹字面量：
miniapp表示微信小程序渠道下单 - 对敏感字段加粗：
payment_method必须与用户实名认证等级匹配（L1→余额，L2→微信，L3→银行卡） - 启用代码高亮后，JSON 示例中的关键键名自动变色，视觉上强化记忆点
这些细节能减少因字符串拼错、大小写混淆导致的联调失败。
