OpenAPI

身份验证

以 Markdown 格式查看

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

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

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

在规范中配置身份验证

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

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

生成的 SDK 用法：

index.ts
1const client = new Client({
2  token: "ey34..."
3});
openapi.yml
1components:
2  securitySchemes:
3    BearerAuth: # 用户定义的方案名称
4      type: http
5      scheme: bearer

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

openapi.yml
1components:
2  securitySchemes:
3    BearerAuth:
4      type: http
5      scheme: bearer
6      x-fern-bearer:
7        name: apiKey
8        env: PLANTSTORE_API_KEY
openapi.yml
1components:
2  securitySchemes:
3    BasicAuth: # 用户定义的方案名称
4      type: http
5      scheme: basic

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

openapi.yml
1components:
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
openapi.yml
1components:
2  securitySchemes:
3    ApiKeyAuth: # 用户定义的方案名称
4      type: apiKey
5      in: header
6      name: X_API_KEY

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

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

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

生成的 SDK 用法：

index.ts
1// 使用 process.env.PLANTSTORE_API_KEY
2const client = new PlantStoreClient();
3
4// 或显式提供
5const client = new PlantStoreClient({
6  apiKey: "your-api-key"
7});
generators.yml
1auth-schemes:
2  BearerAuth: # 用户定义的方案名称
3    scheme: bearer
4    token:
5      name: apiKey
6      env: MY_API_KEY
generators.yml
1auth-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 中移除它。

generators.yml
1auth-schemes:
2  ApiKeyAuth: # 用户定义的方案名称
3    header: X-API-Key
4    name: apiKey
5    env: MY_API_KEY
6    prefix: "Token "
专业版和企业版功能

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

generators.yml
1auth-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"。