openapi3.Unmarshal
返回从给定资源反序列化得到的 OpenAPI 3 描述。
这一页解决什么问题
Hugo 站点里要渲染 API 文档时,通常手上有一份 OpenAPI 3 定义(JSON 或 YAML)。openapi3.Unmarshal 把这份定义读成可遍历的数据结构,于是你可以用模板列出每个路径、每个操作、每个参数,而不必手写一遍。它还会自动解析外部引用(本地与远程),返回一份完整的 OpenAPI 描述。
返回的对象由 kin-openapi 创建,很多字段是结构体或指针,需要用访问器(例如 .Paths.Map),不能当成普通映射直接 index。
什么时候用,什么时候别用
该用:
- 从
assets/里的 OpenAPI 文件生成 API 参考页; - 需要遍历路径 / 操作 / schema,并用本站模板样式呈现;
- 定义里带外部
$ref,希望 Hugo 在构建时一并抓取(远程引用需要getremote选项)。
别用:
- 只想把 JSON 原样打印出来 → 用
transform.Remarshal或直接jsonify; - 需要运行时请求 API → Hugo 是静态构建,
openapi3.Unmarshal只处理定义文件; - 定义是 OpenAPI 2 / Swagger → 上游未提供转换支持。
用法
传给 openapi3.Unmarshal 函数的资源必须是 OpenAPI 文档,通常是 JSON 或 YAML 格式。这个资源可以是全局资源,也可以是远程资源。
该函数会自动解析并纳入所有外部引用(本地与远程都包括),返回一份完整的 OpenAPI 描述,完整描述某个 API 的对外接口及其语义。
openapi3.Unmarshal 函数接受一个选项映射。
getremote- (0.153.0 新增)
- (
map) 这是resources.GetRemote函数的选项映射,在 OpenAPI 文档包含远程外部引用时很有用。
示例
下面的示例演示如何反序列化远程资源与全局资源,以及如何检查结果。
远程资源
处理远程资源:
{{ $api := "" }}
{{ $url := "https://petstore.swagger.io/v2/swagger.json" }}
{{ $opts := dict
"headers" (dict "Authorization" "Bearer abcd")
}}
{{ with try (resources.GetRemote $url $opts) }}
{{ with .Err }}
{{ errorf "%s" . }}
{{ else with .Value }}
{{ $api = openapi3.Unmarshal . (dict "getremote" $opts) }}
{{ else }}
{{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
{{ end }}上例中,同一个 HTTP Authorization 头既用于 resources.GetRemote 函数发起的首次远程请求,也用于 openapi.Unmarshal 函数在获取远程外部引用时发起的后续请求。
全局资源
处理全局资源:
{{ $api := "" }}
{{ $opts := dict
"method" "post"
"key" now.UnixNano
}}
{{ with resources.Get "api/petstore.json" }}
{{ $api = openapi3.Unmarshal . (dict "getremote" $opts) }}
{{ end }}对全局资源而言,以 / 开头的本地外部引用路径相对于 assets 目录解析,其余本地路径相对于入口点解析。上例中,本地路径相对于 assets/api/petstore.json 解析。
检查结构
检查反序列化得到的数据结构:
<pre>{{ debug.Dump $api }}</pre>列出每个 API 路径的 GET 与 POST 操作:
{{ range $path, $details := $api.Paths.Map }}
<p>{{ $path }}</p>
<dl>
{{ with $details.Get }}
<dt>GET</dt>
<dd>{{ .Summary }}</dd>
{{ end }}
{{ with $details.Post }}
<dt>POST</dt>
<dd>{{ .Summary }}</dd>
{{ end }}
</dl>
{{ end }}Hugo 会把它渲染为:
<p>/pets</p>
<dl>
<dt>GET</dt>
<dd>List all pets</dd>
<dt>POST</dt>
<dd>Create a pet</dd>
</dl>
<p>/pets/{petId}</p>
<dl>
<dt>GET</dt>
<dd>Info for a specific pet</dd>
</dl>完整示例(实测)
assets/api/petstore.json:
{
"openapi": "3.0.0",
"info": { "title": "Swagger Petstore", "version": "1.0.0" },
"paths": {
"/pets": {
"get": { "summary": "List all pets", "responses": { "200": { "description": "ok" } } },
"post": { "summary": "Create a pet", "responses": { "200": { "description": "ok" } } }
},
"/pets/{petId}": {
"get": { "summary": "Info for a specific pet", "responses": { "200": { "description": "ok" } } }
}
}
}模板:
{{ with resources.Get "api/petstore.json" }}
{{ $api := openapi3.Unmarshal . }}
<p>{{ $api.Info.Title }} {{ $api.Info.Version }}</p>
{{ range $path, $details := $api.Paths.Map }}
<p>{{ $path }}</p>
{{ with $details.Get }}<dt>GET</dt><dd>{{ .Summary }}</dd>{{ end }}
{{ with $details.Post }}<dt>POST</dt><dd>{{ .Summary }}</dd>{{ end }}
{{ end }}
{{ end }}Hugo 0.167.0 实测渲染(元素间空白已省略):
<p>Swagger Petstore 1.0.0</p>
<p>/pets</p>
<dt>GET</dt><dd>List all pets</dd>
<dt>POST</dt><dd>Create a pet</dd>
<p>/pets/{petId}</p>
<dt>GET</dt><dd>Info for a specific pet</dd>你应当看到什么:Paths 必须通过 .Map 访问器遍历;details.Get / details.Post 在没有对应操作时为空,with 会自动跳过。
返回值边界(实测)
| 情况 | 结果 | 是否报错 |
|---|---|---|
| 合法的 OpenAPI 3 JSON | 返回 openapi3.OpenAPIDocument,.Paths.Map 可遍历 |
否 |
resources.Get 找不到资源(返回 nil) |
—— | 是:error calling Unmarshal: interface conversion: interface is nil, not resource.UnmarshableResource |
远程资源 / 远程 $ref |
需要联网,本站未实测;上游「远程资源」示例只给出模板写法,未给出渲染输出 | —— |