Pyroscope API 文档生成器:基于 OpenAPI v3 自动生成 Connect API 参考文档的 Go 工具
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):
- 递归扫描输入目录下所有
.yaml/.yml文件; - 用
github.com/getkin/kin-openapi/openapi3解析每个 OpenAPI spec; - 按服务(API group)聚合端点,只保留标记为
scope/public的公共接口; - 为每个端点渲染请求字段表格(字段、描述、示例、枚举值);
- 基于 schema 中的示例值自动生成 cURL 与 Python 两种调用示例;
- 将全部内容通过 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.yamlmetastore/v1/*.openapi.yaml(compactor、index、query、tenant、types、raft_log)settings/v1/setting.openapi.yaml、settings/v1/recording_rules.openapi.yamltypes/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 存入specsmap; - 调用
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" }}。其逻辑为:
- 遍历所有 spec 的所有 path,筛选出以传入的 group 前缀开头的路径(如
/push.v1.PusherService); - 只保留带
scope/publictag 的操作(GET优先,否则POST); - 对收集到的 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):
template.ParseFiles解析模板文件;- 创建输出文件(必要时先
os.MkdirAll创建输出目录); - 将
templateSpecs{Specs, InlineMetadata}作为数据执行模板(模板名取文件 basename); - 成功后在控制台打印
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/publictag 的端点会被输出,内部端点(如AnalyzeQuery)不会出现在生成文档中,这是有意的设计而非遗漏; - 生成的示例中 URL 固定为
http://localhost:4040,生产环境使用时需替换为实际服务地址; - 示例依赖本机可用的
date、base64(curl 侧)与requests、datetime、base64(Python 侧)运行时。
延伸阅读
- 工具实现:tools/api-docs-generator/main.go、tools/api-docs-generator/curl.go、tools/api-docs-generator/python.go
- 输入规范来源:api/connect-openapi/base.yaml、api/buf.gen.yaml
- 生成的 OpenAPI 示例:api/connect-openapi/gen/querier/v1/querier.openapi.yaml
- 输出模板:docs/sources/reference-server-api/index.template
- 生成产物(默认输出):docs/sources/reference-server-api/index.md