在 API 参考中编写 Markdown 内容

Fern Docs 允许您在 API 参考文档中编写 Markdown 内容。此功能对于为 API 端点提供额外的上下文、示例或解释非常有用。

向端点添加 Markdown 内容

您可以在 OpenAPI 的 API 定义中使用 description 字段来包含 Markdown 内容。这包括标注、代码块和其他组件。

您还可以使用 <Footer> 组件在 API 参考页面底部（响应部分下方）添加内容。<Footer> 组件内的内容可以包含任何 Markdown 内容或组件，例如链接、标注或代码块。

1 paths:
2   /pets:
3     get:
4       summary: List all pets
5       description: |
6         获取系统中所有宠物的列表。
7 
8         <Note>此端点需要身份验证。</Note>
9 
10         <Footer>
11         ## 相关端点
12 
13         - [创建宠物](/api-reference/pets/create)
14         - [更新宠物](/api-reference/pets/update)
15         </Footer>

API 链接语法

Use api: link syntax to link to API endpoints or API Reference sections in any Markdown content. Fern resolves these links at build time, so you don’t need to hardcode slugs.

Link to an endpoint

Use api:METHOD/path, where METHOD is an HTTP method (GET, POST, PUT, PATCH, DELETE) and /path is the endpoint path from your API definition. Path parameters use curly braces, such as api:GET/v2/payments/{paymentId}.

For projects with multiple APIs, prefix with the API name: api:API-NAME:METHOD/path.

Markdown

1 View the [Current user information](api:mcp-tools:GET/api/fern-docs/whoami) endpoint.

Link to the root of an API Reference section

Use api:apiName, where apiName matches the API name in your generators.yml file. This is useful when your project has multiple APIs and you want to link to the root landing page of a specific API Reference.

Markdown

1 Explore the [Plant Store API](api:plant-store) reference.

以下是 api: 链接语法在 API 定义中的示例：

1 paths:
2   /orders:
3     post:
4       summary: Create an order
5       description: |
6         创建新订单。要列出所有订单，
7         请使用[列出订单](api:GET/v2/orders)。

添加概览页面

您还可以创建一个 Markdown 页面来提供 API 参考的概述。此页面可以包含有关 API 的一般信息，例如身份验证要求、速率限制或其他重要详细信息。

要添加概览页面，请在 fern/ 文件夹中创建一个 Markdown 文件，并在 docs.yml 文件中链接到它：

docs.yml

1 navigation:
2   - api: API Reference
3     summary: ./pages/api-summary.mdx

通过包含 summary 字段，API Reference 部分标题将链接到 api-summary.mdx 页面。

在端点之间添加 Markdown 内容

您还可以在 API 参考中的端点之间包含 Markdown 内容。此内容可以提供适用于多个端点的上下文或解释。

此功能需要您在 docs.yml 文件中使用 layout 字段，这在自定义 API 参考指南中有详细说明。

要在端点之间添加 Markdown 内容，请在 fern/ 文件夹中创建一个 Markdown 文件，并在 docs.yml 文件中链接到它：

docs.yml

1 navigation:
2   - api: API Reference
3     layout:
4       - pet:
5           - page: Pet CRUD
6             path: ./pages/pet-crud.mdx
7           - addPet
8           - updatePet
9           - deletePet
10           - page: Pet Search
11             path: ./pages/pet-search.mdx
12           - findPets
13           - findPetsByStatus
14           - findPetsByTags
15           - findPetsByType
16           - findPetsByBreed