docdoc 文档

接口文档写作

编写 API 参考类文档时，给页面加一行接口标记（文件首个非空行），构建器会把页面渲染为接口文档形态：参数围栏表格化、类型三视图切换、附 Try 调试面板。

三种标记

标记 用途 示例
<!--HTTP ACTION 路径--> HTTP 接口 <!--HTTP POST /api/v1/sites-->
<!--NATS 主题--> NATS request-reply 接口 <!--NATS user.by-id-->
<!--TYPE 类型名--> 类型对象说明页 <!--TYPE SiteDTO-->

- @base= 可选，声明 Try 面板的目标 Base URL；标记路径以 / 开头表示相对服务器根，否则相对站点根。

紧随一级标题的 #### 单行描述会并入标题，作为侧栏条目第二行、搜索结果与翻页链接的副标题。

参数围栏

用 jsonschema 系列围栏声明参数，构建期渲染为对照表格：

```jsonschema:query
{
  "type": "object",
  "properties": {
    "keyword": { "type": "string", "description": "检索关键词" }
  },
  "required": ["keyword"],
  "x-example": { "keyword": "错误码" }
}
```

围栏种类：parameters（路径参数）、headers、query、body、response、type。参数类围栏必须携带顶层 x-example 示例对象，为「Example 数据」视图与 Try 面板预填提供数据。

类型字段可用 {#ref: TypeName} 引用类型对象页的字段表，并继承其示例。