在 API Reference 中编写 Markdown 内容

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

为端点添加 Markdown 内容

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

您还可以使用 <Footer> 组件添加内容，该内容将在 API Reference 页面底部、响应部分下方呈现。<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 Reference 的概述。此页面可以包含有关您的 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 Reference 的端点之间包含 Markdown 内容。此内容可以提供适用于多个端点的上下文或说明。

此功能要求您在 docs.yml 文件中使用 layout 字段，这在自定义您的 API Reference 指南中有描述。

要在端点之间添加 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