Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
title: 环境配置
description: 列出生产、预发布和开发等环境
sidebar-title: 环境配置
title: 环境
description: 列出生产、暂存和开发等环境
noindex: true
---

您可以指定服务器部署的环境
您可以指定部署服务器的环境

## 单 URL 环境
## 单URL环境

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] reported by reviewdog 🐶
[FernStyles.Headings] '单URL环境' should use sentence-style capitalization.


```yaml title="api.yml"
name: api
Expand All @@ -17,9 +17,9 @@ environments:
url: https://www.staging.yoursite.com
```

## 每个环境多个 URL
## 每个环境多个URL

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] reported by reviewdog 🐶
[FernStyles.Headings] '每个环境多个URL' should use sentence-style capitalization.


您可以为每个环境指定多个 URL。如果您有微服务架构,并且希望单个 SDK 与多个服务器交互,这将很有帮助。
您可以为每个环境指定多个URL。如果您有微服务架构,并希望单个SDK与多个服务器交互,这将很有帮助。

```yaml title="api.yml"
environments:
Expand All @@ -33,7 +33,7 @@ environments:
Plants: https://plants.staging.yoursite.com
```

如果您选择使用此功能,必须为您定义的每个服务指定一个 `url`:
如果您选择使用此功能,必须为定义的每个服务指定一个`url`:

```yaml title="auth.yml"
service:
Expand All @@ -44,7 +44,7 @@ service:

## 默认环境

您也可以提供默认环境
您还可以提供默认环境

```yaml title="api.yml"
name: api
Expand All @@ -56,18 +56,18 @@ environments:
default-environment: Production
```

<Note>通过提供默认环境,生成的 SDK 将设置为开箱即用地访问该 URL。</Note>
<Note>通过提供默认环境,生成的SDK将设置为开箱即用地访问该URL。</Note>

## URL 模板
## URL模板

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📝 [vale] reported by reviewdog 🐶
[FernStyles.Headings] 'URL模板' should use sentence-style capitalization.


<Note>URL 模板目前仅支持 Python 和 Java SDK 生成。</Note>
<Note>URL模板目前仅支持Python和Java SDK生成。</Note>

对于跨多个区域或环境部署的 API,您可以定义带有变量占位符的 URL 模板,SDK 用户可以在运行时进行自定义。要设置此功能
对于跨多个区域或环境部署的API,您可以定义带有变量占位符的URL模板,SDK用户可以在运行时自定义。设置方法

1. 在 `urls` 下定义您的静态基础 URL——这些会出现在生成的环境枚举中
2. 为每个服务添加带有 `{variable}` 占位符的 `url-templates`(例如,`https://api.{region}.example.com/v1`)。Fern 将这些作为 SDK 中的可配置参数公开
3. 提供 `default-urls` 作为具体的回退选项,这样 SDK 用户无需提供变量就能获得开箱即用的客户端
4. 为每个服务列出可用的 `variables`,每个变量都有一个 `id`、一个 `default` 值,以及一个可选的 `values` 列表来约束允许的选项。
1. 在`urls`下定义静态基础URL——这些将出现在生成的环境枚举中
2. 为每个服务添加带有`{variable}`占位符的`url-templates`(例如,`https://api.{region}.example.com/v1`)。Fern将这些作为SDK中的可配置参数公开
3. 提供`default-urls`作为具体的后备方案,以便SDK用户无需提供变量即可获得开箱即用的客户端
4. 列出每个服务的可用`variables`,每个变量具有`id`、`default`值和可选的`values`列表来约束允许的选项。

```yaml title="api.yml"
environments:
Expand Down Expand Up @@ -106,17 +106,17 @@ default-environment: RegionalApiServer
```

## 基础路径
如果您希望所有端点都添加路径前缀,请使用 `base-path`。
如果您希望所有端点都带有路径前缀,请使用`base-path`。

在下面的示例中,每个端点都添加了 `/v1` 前缀:
在下面的示例中,每个端点都带有`/v1`前缀:
```yaml title="api.yml"
name: api
base-path: /v1
```

## 受众

如果您有列出的环境需要过滤,可以利用受众功能。
如果您有想要筛选的已列出环境,可以利用受众功能。

```yaml title="api.yml"
audiences:
Expand All @@ -129,4 +129,4 @@ environments:
url: https://api.buildwithfern.com
audiences:
- external
```
```
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
---
title: 错误处理
description: 指定错误类型和模式
sidebar-title: 错误处理
noindex: true
---

为了以惯用方式生成 SDK,Fern 需要知道在解析端点响应时如何区分不同的错误。
为了生成符合习惯的 SDK,Fern 需要知道在解析端点响应时如何区分不同的错误。

### 按状态码区分
### 通过状态码区分

您可以指定 Fern 按状态码区分。这意味着在每个端点上,列出的每个错误都必须具有不同的 HTTP 状态码。
您可以指定 Fern 通过状态码进行区分。这意味着在每个端点上,列出的每个错误都必须具有不同的 HTTP 状态码。

<CodeBlock title="api.yml">
```yaml
Expand All @@ -18,9 +18,9 @@ error-discrimination:
```
</CodeBlock>

### 按错误名称区分
### 通过错误名称区分

您可以指定 Fern 按错误名称区分。如果您选择此策略,那么 Fern 将假设每个错误响应都有一个额外的属性来表示错误名称。
您可以指定 Fern 通过错误名称进行区分。如果选择此策略,则 Fern 将假设每个错误响应都有一个额外的属性来表示错误名称。

如果您使用 Fern 生成服务器端代码,那么此选项提供了最大的灵活性。否则,您可能希望使用状态码区分策略。

Expand All @@ -35,7 +35,7 @@ error-discrimination:

### 全局错误

您可以导入并列出将由每个端点抛出的错误
您可以导入和列出将由每个端点抛出的错误

<CodeBlock title="api.yml">
```yaml
Expand All @@ -46,4 +46,4 @@ errors:
- commons.NotFoundError
- commons.BadRequestError
```
</CodeBlock>
</CodeBlock>
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
---
title: 全局配置
description: 指定全局请求头、路径参数或查询参数,以包含在每个请求中
sidebar-title: 全局配置
description: 指定全局请求头、路径参数或查询参数,以便在每个请求中包含
noindex: true
---

`api.yml` 配置支持全局配置,如请求头和路径参数。

## 全局请求头

您可以指定要包含在每个请求中的请求头
您可以指定要在每个请求中包含的请求头

<CodeBlock title="api.yml">
```yaml
Expand All @@ -18,11 +18,11 @@ headers:
```
</CodeBlock>

`api.yml` 中定义全局请求头时,您必须[在端点示例中包含它们](/api-definitions/ferndef/examples#examples-with-headers)。
当您在 `api.yml` 中定义全局请求头时,必须[在端点示例中包含它们](/api-definitions/ferndef/examples#examples-with-headers)。

## 全局路径参数

您可以指定要包含在每个请求中的路径参数
您可以指定要在每个请求中包含的路径参数

<CodeBlock title="api.yml">
```yaml
Expand All @@ -36,7 +36,7 @@ path-parameters:

### 覆盖基础路径

如果您有某些端点不在配置的 `base-path` 下,您可以在端点级别覆盖 `base-path`。
如果您有某些端点不位于配置的 `base-path` 下,可以在端点级别覆盖 `base-path`。

```yml imdb.yml {5}
service:
Expand All @@ -51,12 +51,12 @@ service:

## 全局查询参数

目前还不能指定要包含在每个请求中的查询参数
如果您希望看到这个功能,请为[此问题](https://github.com/fern-api/fern/issues/2930)投票。
您还不能指定要在每个请求中包含的查询参数
如果您希望看到此功能,请为[此问题](https://github.com/fern-api/fern/issues/2930)投票。

## 幂等性请求头

配置幂等性请求头来定义 [SDK 用户](/learn/sdks/deep-dives/idempotency)可以为安全请求重试指定的请求头。您还必须[将每个端点标记为幂等](/learn/api-definitions/ferndef/endpoints/overview#idempotent-endpoints)才能公开这些请求头。当两者都配置时,Fern 生成的 SDK 会将这些请求头作为幂等端点调用的参数公开。
配置幂等性请求头以定义 [SDK 用户](/learn/sdks/deep-dives/idempotency)可以为安全请求重试指定的请求头。您还必须[将每个端点标记为幂等](/learn/api-definitions/ferndef/endpoints/overview#idempotent-endpoints)才能公开这些请求头。当两者都配置时,Fern 生成的 SDK 会将这些请求头作为幂等端点调用的参数公开。

```yaml title="api.yml"
name: api
Expand All @@ -66,4 +66,4 @@ idempotency-headers:
Idempotency-Expiration: optional<integer>
```

`idempotency-headers` 中的每个键是 HTTP 请求头名称,值是类型。然后 [SDK 用户](/learn/sdks/deep-dives/idempotency)可以在调用幂等端点时指定这些请求头
`idempotency-headers` 中的每个键都是 HTTP 请求头名称,值是类型。[SDK 用户](/learn/sdks/deep-dives/idempotency)然后可以在调用幂等端点时指定这些请求头
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
title: api.yml 配置文件
description: 使用 Fern Definition 格式时,api.yml 文件包含通用 API 配置。
sidebar-title: api.yml 配置文件
description: 在使用 Fern Definition 格式时,api.yml 文件包含通用 API 配置。
noindex: true
---

`fern/` 文件夹中有一个名为 `api.yml` 的特殊文件,其中包含所有 API 级别的配置
一个 `fern/` 文件夹包含一个名为 `api.yml` 的特殊文件,其中包括所有 API 范围的配置

```bash {5}
fern/
Expand All @@ -19,7 +19,7 @@ fern/

## API 名称

此名称用于在您的组织中唯一标识您的 API。如果您只有一个 API,那么 `api` 是一个合适的名称
此名称用于在您的组织中唯一标识您的 API。如果您只有一个 API,那么 `api` 就是一个足够的名称

<CodeBlock title="api.yml">
```yaml
Expand All @@ -42,7 +42,7 @@ docs: |

## API 版本

您可以定义基于请求头的 API 版本控制方案,例如 `X-API-Version`。支持的版本和默认值的指定方式如下
您可以定义基于请求头的 API 版本控制方案,例如 `X-API-Version`。支持的版本和默认值指定如下

<CodeBlock title="api.yml">
```yaml
Expand All @@ -54,4 +54,4 @@ version:
- "2.0.0"
- "latest"
```
</CodeBlock>
</CodeBlock>
35 changes: 17 additions & 18 deletions fern/translations/zh/products/api-def/ferndef/audiences.mdx
Original file line number Diff line number Diff line change
@@ -1,27 +1,26 @@
---
title: Fern Definition 中的受众
subtitle: 在您的 Fern Definition 中使用受众,为不同的 API 消费者群体进行分组
sidebar-title: Fern Definition 中的受众
title: Fern 定义中的受众
subtitle: Fern 定义中使用受众来为不同的 API 消费者群体进行分段
noindex: true
---


<Markdown src="/snippets/team-or-pro-plan.mdx"/>

受众是为不同消费者分组 API 的有用工具。您可以配置 Fern Docs 发布特定于某个`受众`的文档。您也可以在 [OpenAPI 规范中使用受众](/learn/api-definitions/openapi/extensions/audiences)。
受众是一个用于为不同消费者分段 API 的有用工具。您可以配置 Fern Docs 来发布特定于某个`受众`的文档。您也可以[在 OpenAPI 规范中使用受众](/learn/api-definitions/openapi/extensions/audiences)。

受众的常见示例包括:

- 内部消费者(例如,使用 API 的前端开发人员)
- Beta 测试人员
- Beta 测试者
- 客户

默认情况下,如果未指定受众,则所有消费者都可以访问
默认情况下,如果没有指定受众,所有消费者都可以访问

## 配置

Fern Definition 具有为不同端点、类型和属性标记不同受众的一级概念。
Fern 定义具有为不同端点、类型和属性标记不同受众的一级概念。

要在 Fern Definition 中使用受众,请将其添加到 `api.yml` 中。
要在 Fern 定义中使用受众,请将其添加到 `api.yml` 中。

在下面的示例中,我们为 `internal`、`beta` 和 `customer` 群体创建了受众:

Expand All @@ -33,7 +32,7 @@ audiences:
- customers
```

## 端点的受众
## 端点受众

要为特定消费者标记端点,请添加包含相关群体的 `audience`。

Expand All @@ -51,9 +50,9 @@ service:
...
```

## 类型的受众
## 类型受众

类型也可以标记为不同的受众
类型也可以为不同受众进行标记

在此示例中,`Email` 类型对内部和 beta 消费者可用:

Expand All @@ -67,9 +66,9 @@ Email:
- beta
```

## 属性的受众
## 属性受众

类型的属性也可以标记为不同的受众
类型的属性也可以为不同受众进行标记

在此示例中,`to` 属性仅对 beta 消费者可用:

Expand All @@ -85,7 +84,7 @@ Email:
- beta
```

## SDK 的受众
## SDK 受众

在 `generators.yml` 中,您可以应用受众过滤器,以便只有某些端点传递给生成器。

Expand All @@ -100,11 +99,11 @@ groups:
...
```

## 文档的受众
## 文档受众

如果生成 Fern Docs,请更新您的 `docs.yml` 配置以包含您的受众。

以下示例展示了如何配置您的 `docs.yml` `customers` 受众发布文档:
以下示例显示如何配置 `docs.yml` 来为 `customers` 受众发布文档:

<CodeBlock title='docs.yml'>
```yaml {3-4}
Expand All @@ -113,4 +112,4 @@ navigation:
audiences:
- customers
```
</CodeBlock>
</CodeBlock>
Loading
Loading