身份验证

Fern 支持两种配置身份验证的方式：

在您的 OpenAPI 规范中使用 securitySchemes — 标准方法，保持认证配置的可移植性，并与其他 OpenAPI 工具兼容。
在 generators.yml 中使用 auth-schemes — 使用此方式自定义参数名称和环境变量，覆盖规范中定义的内容，或配置 OAuth（在 OpenAPI 中不可用）。

您的身份验证配置适用于生成的 SDK 和 API 浏览器。所有 SDK 都支持凭证的直接配置和环境变量。如果您在两个地方定义了相同的方案，则以 generators.yml 为准。

在规范中配置身份验证

在 components.securitySchemes 中定义您的方案，然后使用 security 属性全局应用或按端点应用。

openapi.yml

1 # 定义方案
2 components:
3   securitySchemes:
4     BearerAuth: # 用户定义的方案名称
5       type: http
6       scheme: bearer
7 
8 # 在所有端点全局应用
9 security:
10   - BearerAuth: []

生成的 SDK 用法：

index.ts

1 const client = new Client({
2   token: "ey34..."
3 });

Bearer

openapi.yml

1 components:
2   securitySchemes:
3     BearerAuth: # 用户定义的方案名称
4       type: http
5       scheme: bearer

要自定义参数名称和环境变量，请添加 x-fern-bearer：

openapi.yml

1 components:
2   securitySchemes:
3     BearerAuth:
4       type: http
5       scheme: bearer
6       x-fern-bearer:
7         name: apiKey
8         env: PLANTSTORE_API_KEY

Basic

openapi.yml

1 components:
2   securitySchemes:
3     BasicAuth: # 用户定义的方案名称
4       type: http
5       scheme: basic

要自定义参数名称和环境变量，请添加 x-fern-basic：

openapi.yml

1 components:
2   securitySchemes:
3     BasicAuth:
4       type: http
5       scheme: basic
6       x-fern-basic:
7         username:
8           name: clientId
9           env: PLANTSTORE_CLIENT_ID
10         password:
11           name: clientSecret
12           env: PLANTSTORE_CLIENT_SECRET

API key

openapi.yml

1 components:
2   securitySchemes:
3     ApiKeyAuth: # 用户定义的方案名称
4       type: apiKey
5       in: header
6       name: X_API_KEY

要自定义参数名称和环境变量，请添加 x-fern-header：

openapi.yml

1 components:
2   securitySchemes:
3     ApiKeyAuth:
4       type: apiKey
5       in: header
6       name: X_API_KEY
7       x-fern-header:
8         name: apiToken
9         env: PLANTSTORE_API_KEY
10         prefix: "Token "

prefix 选项会自动在 API 密钥前添加字符串，当您的 API 需要 "Bearer abc123" 或 "Token abc123" 等格式时很有用。

多种认证方案

配置端点以支持多种身份验证方案或组合。在 security 部分，多个顶级项目是 OR 选项，而单个项目内的方案通过 AND 组合。

openapi.yml

1 components:
2   securitySchemes:
3     bearerAuth: # 用户定义的方案名称
4       type: http
5       scheme: bearer
6     basicAuth: # 用户定义的方案名称
7       type: http
8       scheme: basic
9     apiKey: # 用户定义的方案名称
10       type: apiKey
11       in: header
12       name: X-API-Key
13 
14 paths:
15   /plant/search/status:
16     get:
17       summary: Search plants by status
18       security:
19         - bearerAuth: []           # 选项 1：仅 Bearer token
20         - basicAuth: []            # 选项 2：Basic auth 和 API key
21           apiKey: []

在此示例中，用户可以使用 bearer token 进行身份验证，或者同时使用 basic auth 和 API key。

在多种方案中使用 OAuth 客户端凭证时，请确保 OpenAPI 规范的 security 部分中的方案名称与 generators.yml 中定义的名称匹配。

在 `generators.yml` 中自定义或覆盖身份验证

在 auth-schemes 中定义您的方案，然后使用 api.auth 将其作为所有端点的默认值：

generators.yml

1 # 定义方案
2 auth-schemes:
3   BearerAuth: # 用户定义的方案名称
4     scheme: bearer
5     token:
6       name: apiKey
7       env: PLANTSTORE_API_KEY
8 
9 # 将其作为所有端点的默认值
10 api:
11   auth: BearerAuth
12   specs:
13     - openapi: ./openapi.yml

有关完整的配置选项，请参见 auth-schemes 参考。您还可以为特定 SDK 覆盖身份验证设置。

生成的 SDK 用法：

index.ts

1 // 使用 process.env.PLANTSTORE_API_KEY
2 const client = new PlantStoreClient();
3 
4 // 或显式提供
5 const client = new PlantStoreClient({
6   apiKey: "your-api-key"
7 });

Bearer

generators.yml

1 auth-schemes:
2   BearerAuth: # 用户定义的方案名称
3     scheme: bearer
4     token:
5       name: apiKey
6       env: MY_API_KEY

Basic

generators.yml

1 auth-schemes:
2   BasicAuth: # 用户定义的方案名称
3     scheme: basic
4     username:
5       name: clientId
6       env: MY_CLIENT_ID
7     password:
8       name: clientSecret
9       env: MY_CLIENT_SECRET

在 username 或 password 上设置 omit: true 以从生成的 SDK 中移除它。

API key

generators.yml

1 auth-schemes:
2   ApiKeyAuth: # 用户定义的方案名称
3     header: X-API-Key
4     name: apiKey
5     env: MY_API_KEY
6     prefix: "Token "

OAuth 客户端凭证

专业版和企业版功能

此功能在专业版和企业版计划中提供。请联系 support@buildwithfern.com 开始使用。

generators.yml

1 auth-schemes:
2   OAuth: # 用户定义的方案名称
3     scheme: oauth
4     type: client-credentials
5     client-id-env: OAUTH_CLIENT_ID
6     client-secret-env: OAUTH_CLIENT_SECRET
7     get-token:
8       endpoint: "POST /oauth/token"
9       request-properties:
10         client-id: client_id
11         client-secret: client_secret
12       response-properties:
13         access-token: access_token
14         expires-in: expires_in
15         refresh-token: refresh_token
16     refresh-token:
17       endpoint: "POST /oauth/refresh"
18       request-properties:
19         refresh-token: refresh_token
20       response-properties:
21         access-token: access_token
22         expires-in: expires_in

endpoint 值引用您的 OpenAPI 规范中的路径。当返回 expires-in 时，SDK 会在 token 过期前自动刷新。

如果您的 API 使用命名空间（多个 API 规范），请在端点前加上命名空间和 ::。例如，"payments::POST /oauth/token"。

Fern 支持两种配置身份验证的方式：

在您的 OpenAPI 规范中使用 securitySchemes — 标准方法，保持认证配置的可移植性，并与其他 OpenAPI 工具兼容。
在 generators.yml 中使用 auth-schemes — 使用此方式自定义参数名称和环境变量，覆盖规范中定义的内容，或配置 OAuth（在 OpenAPI 中不可用）。

在规范中配置身份验证

在 components.securitySchemes 中定义您的方案，然后使用 security 属性全局应用或按端点应用。

openapi.yml

1 # 定义方案
2 components:
3   securitySchemes:
4     BearerAuth: # 用户定义的方案名称
5       type: http
6       scheme: bearer
7 
8 # 在所有端点全局应用
9 security:
10   - BearerAuth: []

生成的 SDK 用法：

index.ts

1 const client = new Client({
2   token: "ey34..."
3 });

Bearer

openapi.yml

1 components:
2   securitySchemes:
3     BearerAuth: # 用户定义的方案名称
4       type: http
5       scheme: bearer

要自定义参数名称和环境变量，请添加 x-fern-bearer：

openapi.yml

1 components:
2   securitySchemes:
3     BearerAuth:
4       type: http
5       scheme: bearer
6       x-fern-bearer:
7         name: apiKey
8         env: PLANTSTORE_API_KEY

Basic

openapi.yml

1 components:
2   securitySchemes:
3     BasicAuth: # 用户定义的方案名称
4       type: http
5       scheme: basic

要自定义参数名称和环境变量，请添加 x-fern-basic：

openapi.yml

1 components:
2   securitySchemes:
3     BasicAuth:
4       type: http
5       scheme: basic
6       x-fern-basic:
7         username:
8           name: clientId
9           env: PLANTSTORE_CLIENT_ID
10         password:
11           name: clientSecret
12           env: PLANTSTORE_CLIENT_SECRET

API key

openapi.yml

1 components:
2   securitySchemes:
3     ApiKeyAuth: # 用户定义的方案名称
4       type: apiKey
5       in: header
6       name: X_API_KEY

要自定义参数名称和环境变量，请添加 x-fern-header：

openapi.yml

1 components:
2   securitySchemes:
3     ApiKeyAuth:
4       type: apiKey
5       in: header
6       name: X_API_KEY
7       x-fern-header:
8         name: apiToken
9         env: PLANTSTORE_API_KEY
10         prefix: "Token "

prefix 选项会自动在 API 密钥前添加字符串，当您的 API 需要 "Bearer abc123" 或 "Token abc123" 等格式时很有用。

多种认证方案

配置端点以支持多种身份验证方案或组合。在 security 部分，多个顶级项目是 OR 选项，而单个项目内的方案通过 AND 组合。

openapi.yml

1 components:
2   securitySchemes:
3     bearerAuth: # 用户定义的方案名称
4       type: http
5       scheme: bearer
6     basicAuth: # 用户定义的方案名称
7       type: http
8       scheme: basic
9     apiKey: # 用户定义的方案名称
10       type: apiKey
11       in: header
12       name: X-API-Key
13 
14 paths:
15   /plant/search/status:
16     get:
17       summary: Search plants by status
18       security:
19         - bearerAuth: []           # 选项 1：仅 Bearer token
20         - basicAuth: []            # 选项 2：Basic auth 和 API key
21           apiKey: []

在此示例中，用户可以使用 bearer token 进行身份验证，或者同时使用 basic auth 和 API key。

在多种方案中使用 OAuth 客户端凭证时，请确保 OpenAPI 规范的 security 部分中的方案名称与 generators.yml 中定义的名称匹配。

在 `generators.yml` 中自定义或覆盖身份验证

在 auth-schemes 中定义您的方案，然后使用 api.auth 将其作为所有端点的默认值：

generators.yml

1 # 定义方案
2 auth-schemes:
3   BearerAuth: # 用户定义的方案名称
4     scheme: bearer
5     token:
6       name: apiKey
7       env: PLANTSTORE_API_KEY
8 
9 # 将其作为所有端点的默认值
10 api:
11   auth: BearerAuth
12   specs:
13     - openapi: ./openapi.yml

有关完整的配置选项，请参见 auth-schemes 参考。您还可以为特定 SDK 覆盖身份验证设置。

生成的 SDK 用法：

index.ts

1 // 使用 process.env.PLANTSTORE_API_KEY
2 const client = new PlantStoreClient();
3 
4 // 或显式提供
5 const client = new PlantStoreClient({
6   apiKey: "your-api-key"
7 });

Bearer

generators.yml

1 auth-schemes:
2   BearerAuth: # 用户定义的方案名称
3     scheme: bearer
4     token:
5       name: apiKey
6       env: MY_API_KEY

Basic

generators.yml

1 auth-schemes:
2   BasicAuth: # 用户定义的方案名称
3     scheme: basic
4     username:
5       name: clientId
6       env: MY_CLIENT_ID
7     password:
8       name: clientSecret
9       env: MY_CLIENT_SECRET

在 username 或 password 上设置 omit: true 以从生成的 SDK 中移除它。

API key

generators.yml

1 auth-schemes:
2   ApiKeyAuth: # 用户定义的方案名称
3     header: X-API-Key
4     name: apiKey
5     env: MY_API_KEY
6     prefix: "Token "

OAuth 客户端凭证

专业版和企业版功能

此功能在专业版和企业版计划中提供。请联系 support@buildwithfern.com 开始使用。

generators.yml

1 auth-schemes:
2   OAuth: # 用户定义的方案名称
3     scheme: oauth
4     type: client-credentials
5     client-id-env: OAUTH_CLIENT_ID
6     client-secret-env: OAUTH_CLIENT_SECRET
7     get-token:
8       endpoint: "POST /oauth/token"
9       request-properties:
10         client-id: client_id
11         client-secret: client_secret
12       response-properties:
13         access-token: access_token
14         expires-in: expires_in
15         refresh-token: refresh_token
16     refresh-token:
17       endpoint: "POST /oauth/refresh"
18       request-properties:
19         refresh-token: refresh_token
20       response-properties:
21         access-token: access_token
22         expires-in: expires_in

endpoint 值引用您的 OpenAPI 规范中的路径。当返回 expires-in 时，SDK 会在 token 过期前自动刷新。

如果您的 API 使用命名空间（多个 API 规范），请在端点前加上命名空间和 ::。例如，"payments::POST /oauth/token"。

1	# 定义方案
2	components:
3	securitySchemes:
4	BearerAuth: # 用户定义的方案名称
5	type: http
6	scheme: bearer
7
8	# 在所有端点全局应用
9	security:
10	- BearerAuth: []

1	components:
2	securitySchemes:
3	BearerAuth:
4	type: http
5	scheme: bearer
6	x-fern-bearer:
7	name: apiKey
8	env: PLANTSTORE_API_KEY

1	components:
2	securitySchemes:
3	BasicAuth: # 用户定义的方案名称
4	type: http
5	scheme: basic

1	components:
2	securitySchemes:
3	BasicAuth:
4	type: http
5	scheme: basic
6	x-fern-basic:
7	username:
8	name: clientId
9	env: PLANTSTORE_CLIENT_ID
10	password:
11	name: clientSecret
12	env: PLANTSTORE_CLIENT_SECRET

1	components:
2	securitySchemes:
3	ApiKeyAuth: # 用户定义的方案名称
4	type: apiKey
5	in: header
6	name: X_API_KEY

1	components:
2	securitySchemes:
3	ApiKeyAuth:
4	type: apiKey
5	in: header
6	name: X_API_KEY
7	x-fern-header:
8	name: apiToken
9	env: PLANTSTORE_API_KEY
10	prefix: "Token "

1	# 定义方案
2	auth-schemes:
3	BearerAuth: # 用户定义的方案名称
4	scheme: bearer
5	token:
6	name: apiKey
7	env: PLANTSTORE_API_KEY
8
9	# 将其作为所有端点的默认值
10	api:
11	auth: BearerAuth
12	specs:
13	- openapi: ./openapi.yml

1	// 使用 process.env.PLANTSTORE_API_KEY
2	const client = new PlantStoreClient();
3
4	// 或显式提供
5	const client = new PlantStoreClient({
6	apiKey: "your-api-key"
7	});

1	auth-schemes:
2	ApiKeyAuth: # 用户定义的方案名称
3	header: X-API-Key
4	name: apiKey
5	env: MY_API_KEY
6	prefix: "Token "

1	auth-schemes:
2	OAuth: # 用户定义的方案名称
3	scheme: oauth
4	type: client-credentials
5	client-id-env: OAUTH_CLIENT_ID
6	client-secret-env: OAUTH_CLIENT_SECRET
7	get-token:
8	endpoint: "POST /oauth/token"
9	request-properties:
10	client-id: client_id
11	client-secret: client_secret
12	response-properties:
13	access-token: access_token
14	expires-in: expires_in
15	refresh-token: refresh_token
16	refresh-token:
17	endpoint: "POST /oauth/refresh"
18	request-properties:
19	refresh-token: refresh_token
20	response-properties:
21	access-token: access_token
22	expires-in: expires_in

在规范中配置身份验证

Bearer

Basic

API key

多种认证方案

在 generators.yml 中自定义或覆盖身份验证

Bearer

Basic

API key

OAuth 客户端凭证

专业版和企业版功能

在规范中配置身份验证

Bearer

Basic

API key

多种认证方案

在 generators.yml 中自定义或覆盖身份验证

Bearer

Basic

API key

OAuth 客户端凭证

专业版和企业版功能

在 `generators.yml` 中自定义或覆盖身份验证

在 `generators.yml` 中自定义或覆盖身份验证