Pyroscope API 文档生成器:基于 OpenAPI v3 自动生成 Connect API 参考文档的 Go 工具

原创2026-09-15 11:19:241,628 阅读
文章标签:后端可观测性性能剖析

Pyroscope API 文档生成器:基于 OpenAPI v3 自动生成 Connect API 参考文档的 Go 工具

导读:本文围绕 Pyroscope 仓库中的 tools/api-docs-generator 工具,讲解它是如何把散落在各服务下的 OpenAPI v3 YAML 定义统一聚合,渲染成一份完整的 Markdown 版 Server HTTP API 参考文档。读完本文,你将掌握该工具的 CLI 用法、三个核心 flags、构建方式,以及它在源码层面是如何完成 YAML 扫描、scope/public 过滤、内联元数据提取、cURL / Python 示例自动生成与模板渲染的完整工作链路。

工具定位:为什么需要 API 文档生成器

Pyroscope 是一个持续性能分析(Continuous Profiling)平台,其服务端通过 Connect 协议暴露 HTTP API。Connect API 基于 protobuf 定义生成,天然具备跨协议(HTTP/1.1、HTTP/2、JSON、二进制 protobuf)与 gRPC 兼容能力。为了让外部使用者、SDK 集成方和文档维护者拥有一份统一、准确且可复现的 API 参考,Pyroscope 在仓库中提供了 tools/api-docs-generator:一个用 Go 编写的命令行工具,从 OpenAPI v3 YAML 文件生成统一的 API 文档。

该工具的核心工作流(见 tools/api-docs-generator/main.go):

  1. 递归扫描输入目录下所有 .yaml / .yml 文件;
  2. 用 github.com/getkin/kin-openapi/openapi3 解析每个 OpenAPI spec;
  3. 按服务(API group)聚合端点,只保留标记为 scope/public 的公共接口;
  4. 为每个端点渲染请求字段表格(字段、描述、示例、枚举值);
  5. 基于 schema 中的示例值自动生成 cURL 与 Python 两种调用示例;
  6. 将全部内容通过 Go 标准库 text/template 灌入模板文件,输出单一 Markdown 文档。

生成的默认产物是 docs/sources/reference-server-api/index.md(即仓库文档站的 "Server HTTP API" 参考页),其模板位于 docs/sources/reference-server-api/index.template。

快速上手:用法、Flags 与构建

README 中给出的用法非常简洁,工具以 go run 方式直接运行:

go run . [flags]

三个核心 Flags

Flag 说明 默认值
-input 存放 OpenAPI YAML 文件的目录 api/connect-openapi/gen
-template 用于生成 Markdown 的模板文件 docs/sources/reference-server-api/index.template
-output 生成文档的输出文件 docs/sources/reference-server-api/index.md
-help 显示帮助信息 false

典型示例

# 使用默认路径生成文档
go run .

# 使用自定义路径生成文档
go run . -input ./openapi-specs -template ./custom.template -output ./api-docs.md

# 查看帮助信息
go run . -help

构建为独立二进制

go build -o api-docs-generator .

构建后可直接执行 ./api-docs-generator <a href="https://link.gitcode.com/i/31760c15adc68c87c4b5a84fa4f170d5" target="_blank">flags]。帮助信息中会输出工具简介、用法、示例与全部 flags(实现见 [main.go):

  • 工具描述:从 OpenAPI v3 YAML 文件生成统一 API 文档,处理输入目录中的所有 .yaml / .yml 文件,并用指定模板创建单个 Markdown 文件;
  • 关键说明:只处理标记为 scope/public 的端点,并为每个端点生成 cURL 和 Python 代码示例。

输入侧:OpenAPI YAML 文件从哪来

默认输入目录 api/connect-openapi/gen 中存放着由 buf 的 connect-openapi 插件从 protobuf 生成的 OpenAPI 3.1 规范文件,按服务分目录组织,共 23 个 YAML 文件,例如:

  • push/v1/push.openapi.yaml(写入路径)
  • querier/v1/querier.openapi.yaml(查询路径)
  • ingester/v1/ingester.openapi.yaml(摄取器)
  • storegateway/v1/storegateway.openapi.yaml
  • metastore/v1/*.openapi.yaml(compactor、index、query、tenant、types、raft_log)
  • settings/v1/setting.openapi.yaml、settings/v1/recording_rules.openapi.yaml
  • types/v1/types.openapi.yaml、google/v1/profile.openapi.yaml 等

这些文件由 api/buf.gen.yaml 中的插件配置生成:

plugins:
  - name: connect-openapi
    out: connect-openapi/gen/
    opt:
      - content-types=json
      - trim-unused-types
      - base=connect-openapi/base.yaml

其中 base=connect-openapi/base.yaml 指向 api/connect-openapi/base.yaml,后者定义了 OpenAPI 的基础信息与两个重要 tag:

openapi: 3.1.0
info:
  title: Pyroscope API
  version: v1.0.0
tags:
  - name: scope/public
    description: This operation is considered part of the public API scope
  - name: scope/internal
    description: This operation is considered part of the internal API scope. There are no stability guarantees when using those APIs.

scope 标签:公共 API 与内部 API 的划分

生成器只在聚合端点时过滤出 scope/public。以 querier.openapi.yaml 为例,同一个服务下两个端点被赋予了不同 scope:

paths:
  /querier.v1.QuerierService/AnalyzeQuery:
    post:
      tags:
        - scope/internal      # 内部接口:不进入生成文档
        - querier.v1.QuerierService
  /querier.v1.QuerierService/Diff:
    post:
      tags:
        - scope/public        # 公共接口:会被文档生成器收录
        - querier.v1.QuerierService

这对应文档模板中说明的 API 分类策略:

  • Public APIs(scope/public):被视为稳定接口,破坏性变更会提前通知并提供迁移路径;
  • Internal APIs(scope/internal):用于 Pyroscope 各组件之间内部通信,可能随时变化,外部客户端不应依赖。

源码级工作链路拆解

1. 递归扫描 YAML 文件

findYAMLFiles(main.go)使用 filepath.WalkDir 递归遍历输入目录,收集所有以 .yaml 或 .yml 结尾的文件;若一个文件都没找到,直接返回错误 no YAML files found in <dir>。

2. 解析 spec 与内联元数据提取

对每个 YAML 文件,generateDocs(main.go)做两件事:

  • 用 openapi3.NewLoader() 加载并解析 spec,以相对路径为 key 存入 specs map;
  • 调用 extractInlineMetadata 从原始 YAML 中提取会被 $ref 解析丢失的内联元数据。

extractInlineMetadata(main.go)会导航到 components.schemas,对每个 schema 的属性逐一检查:当属性本身带有 $ref 且其兄弟节点上携带 description 或 examples 时,这些信息在 OpenAPI 库解析后会被丢弃,因此工具需要在解析前先用 go.yaml.in/yaml/v3 直接读取原始 YAML 备份它们。提取到的内容存入 inlinePropertyMetadata{Description, Example} 结构,最终以 file -> schema -> property -> metadata 的三层 map 组织。

单个解析失败的文件只会打印 Warning 并跳过(log.Printf("Warning: failed to parse %s: %v", ...)),不会中断整个生成过程。

3. 按 API group 聚合公共端点

templateSpecs.RenderAPIGroup(path)(main.go)是模板中调用的核心函数,例如模板中的 {{ .RenderAPIGroup "/push.v1.PusherService" }}。其逻辑为:

  1. 遍历所有 spec 的所有 path,筛选出以传入的 group 前缀开头的路径(如 /push.v1.PusherService);
  2. 只保留带 scope/public tag 的操作(GET 优先,否则 POST);
  3. 对收集到的 path 排序后,逐条输出 #### \` 标题、POST操作描述、请求参数表格与代码示例(响应部分以// TODO Responses` 标记留待后续实现)。

4. 请求字段表格生成

writeParameters + writeSchema(main.go)负责生成请求体的 Markdown 表格,表头固定为:

| Field | Description | Example |
|:------|:------------|:--------|

其中字段的收集由 collectParameters 递归完成(main.go),值得注意的细节:

  • 排序规则:start / end 两个时间字段永远排在最前,其余字段按字母序排列;
  • 嵌套对象:对象类型的属性递归展开,前缀以 . 连接(如 labelSelector.selectors);
  • 数组对象:[] 后缀表示数组元素对象,继续递归展开(如 series[].labels);
  • 枚举值:若字段带 Enum,会以 "Possible values: a, b" 形式追加到描述末尾;
  • 隐藏字段:描述中包含 [hidden] 的字段直接跳过,不出现在文档表格中(cleanTableField)。

字段描述与示例的取值优先级也经过精心设计:示例优先取内联元数据,其次取 schema 自身的 examples;描述则在内联元数据存在时覆盖 schema 默认描述。

5. 自动生成 cURL 与 Python 示例

writeExamples(main.go)会为每个公共端点生成一段 {{< code >}} 短代码块,内含 curl 与 python 两种语言的调用示例。

示例值有特殊的动态替换机制:exampleParameters(main.go)把固定的示例时间戳与占位符映射为运行时表达式:

示例值(Key) cURL 表达式 Python 表达式
1676282400000(start) $(expr $(date +%s) - 3600 )000 int((datetime.datetime.now() - datetime.timedelta(hours=1)).timestamp() * 1000)
1676289600000(end) $(date +%s)000 int(datetime.datetime.now().timestamp() * 1000)
PROFILE_BASE64 "$(cat cpu.pb.gz| base64 -w 0)" base64.b64encode(open('cpu.pb.gz', 'rb').read()).decode('ascii')

这样生成出的示例天然表示"最近 1 小时"的时间窗口,而非写死的静态时间戳。

cURL 示例渲染(curl.go)

exampleCurl.render 收集所有带示例值的字段,通过 setBody 组装嵌套 JSON body,并调用 addLabelsToSeries 给 series 补上 __name__、process_cpu 两个默认标签;随后用 json.MarshalIndent 序列化,并做字符串替换把内嵌表达式标记转换为可执行的 bash 语法。最终输出形如:

curl \
  -H "Content-Type: application/json" \
  -d '{
    "start": "$(expr $(date +%s) - 3600 )000",
    "end": "$(date +%s)000"
  }' \
  http://localhost:4040/querier.v1.QuerierService/SelectMergeProfile

请求 URL 由 exampleParams{url: "http://localhost:4040" + path} 拼接,默认指向本地 4040 端口(Pyroscope 默认 HTTP 监听端口)。

Python 示例渲染(python.go)

examplePython.render 输出结构更完整:

import requests
import datetime

body = {
  "start": int((datetime.datetime.now() - datetime.timedelta(hours=1)).timestamp() * 1000),
  "end": int(datetime.datetime.now().timestamp() * 1000)
}
url = 'http://localhost:4040/querier.v1.QuerierService/SelectMergeProfile'
resp = requests.post(url, json=body)
print(resp)
print(resp.content)

这里有个细节:import datetime 与 import base64 是按需添加的——只有当生成的 body 中分别包含 datetime 或 base64 关键字时才会写入对应 import(python.go),避免无意义的冗余导入。

6. 模板渲染与输出

generateUnifiedDoc(main.go):

  1. template.ParseFiles 解析模板文件;
  2. 创建输出文件(必要时先 os.MkdirAll 创建输出目录);
  3. 将 templateSpecs{Specs, InlineMetadata} 作为数据执行模板(模板名取文件 basename);
  4. 成功后在控制台打印 Documentation generated successfully: <output>。

模板 index.template 本身是一份带 Hugo front matter 的 Markdown 文档(title: Server HTTP API、weight: 650 等),其中通过两处占位调用驱动内容生成:

{{ .RenderAPIGroup "/push.v1.PusherService" }}
{{ .RenderAPIGroup "/querier.v1.QuerierService" }}

分别生成 Ingestion Path(写入路径) 与 Querying profiling data(查询路径) 两大章节的端点明细。除生成部分外,模板还固化了认证说明(Pyroscope 本身不含认证层、多租户模式需 X-Scope-OrgID 头)、UTF-8 标签名查询提示,以及 Legacy HTTP API(POST /ingest、GET /pyroscope/render)的参考内容,共同构成最终发布的 Server API 文档。

维护与扩展视角:从源码结构能推断什么

从源码结构看,该工具的设计有几个明显意图:

  • 单一职责:main.go 负责编排与表格渲染,curl.go / python.go 分别封装语言示例生成器,exampler 接口(render(io.Writer, *exampleParams) + name())使新增语言示例只需实现一个结构体;
  • 面向"协议先行"的文档流水线:protobuf 定义 → buf 插件生成 OpenAPI → 生成器聚合为 Markdown,全程无手写 API 描述,保证文档与实现一致;
  • 对 $ref 场景的补偿:内联元数据提取机制(extractInlineMetadata)专门解决 OpenAPI 解析器丢失 $ref 兄弟节点信息的痛点,这是该工具在工程上最精细的部分;
  • 响应文档仍是 TODO:RenderAPIGroup 中的 // TODO Responses 表明当前版本只输出请求侧信息,响应结构尚未纳入自动生成。

使用前提与限制

  • 工具默认路径(api/connect-openapi/gen、docs/sources/reference-server-api/)与仓库布局强绑定,自定义路径时需保证输入目录内确实存在可解析的 OpenAPI YAML,否则会报 no YAML files found;
  • 只有打了 scope/public tag 的端点会被输出,内部端点(如 AnalyzeQuery)不会出现在生成文档中,这是有意的设计而非遗漏;
  • 生成的示例中 URL 固定为 http://localhost:4040,生产环境使用时需替换为实际服务地址;
  • 示例依赖本机可用的 date、base64(curl 侧)与 requests、datetime、base64(Python 侧)运行时。

延伸阅读

登录后查看全文
pyroscope