生成 REST API 参考文档 | Fern Documentation

Fern 从 OpenAPI 规范或 Fern Definition 生成 REST API 参考文档。一旦设置好 API 定义，将其添加到文档中只需要一行配置。

Fern 还支持 gRPC、WebSocket（AsyncAPI 或 Fern Definition）、OpenRPC 和 Webhook 参考文档。

配置

设置项目结构

对于 OpenAPI/AsyncAPI：将规范文件添加到 /fern 目录，并创建一个在 api.specs 部分引用它的 generators.yml

对于 Fern Definition：添加包含 API 定义文件的 definition/ 目录（Fern 会自动检测）

generators.yml

1 api:
2   specs:
3     - openapi: "./openapi.yml"

将 API 参考文档添加到导航

在 docs.yml 的导航中添加 - api: API Reference：

docs.yml

1 navigation:
2   - api: API Reference

Fern 将自动从您的 API 定义中填充端点、类型和代码片段。请求和响应示例使用 AI 生成，显示真实数据而非占位符值。

自定义布局

有关配置选项和布局自定义的完整列表，请参见自定义 API 参考文档布局。

包含多个 API 参考文档

要在文档中包含多个不同的 API 定义，请使用 api-name 属性。api-name 对应包含 API 定义的文件夹名称。

这适用于 OpenAPI 和 Fern Definition 格式的任意组合。例如：

fern

fern.config.json

docs.yml

plant-api

openapi.yml# OpenAPI spec

generators.yml# References the OpenAPI spec

garden-api

definition

api.yml

平铺布局

标签页布局

对于不使用标签页的简单设置，您可以直接在导航中包含多个 API 参考文档：

docs.yml

1 navigation:
2   - api: Plant Store
3     api-name: plant-api   # 匹配包含 API 定义的文件夹名称
4   - api: Garden
5     api-name: garden-api  # 匹配包含 API 定义的文件夹名称