Skip to content

如何在 OpenAPI 中记录 API 认证信息

本指南展示了如何为你的 LangGraph 平台 API 文档自定义 OpenAPI 安全模式。记录完善的安全模式有助于 API 使用者了解如何对 API 进行认证，甚至可以实现客户端的自动生成。有关 LangGraph 认证系统的更多详细信息，请参阅认证与访问控制概念指南。

实现与文档记录

本指南仅涵盖如何在 OpenAPI 中记录你的安全要求。要实现实际的认证逻辑，请参阅如何添加自定义认证。

本指南适用于所有 LangGraph 平台部署（云部署、自带云部署和自托管部署）。如果你未使用 LangGraph 平台，本指南不适用于 LangGraph 开源库的使用场景。

默认方案

默认的安全方案因部署类型而异：

默认情况下，LangGraph 云服务要求在 x-api-key 头部中提供一个 LangSmith API 密钥：

components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
security:
  - apiKeyAuth: []

使用 LangGraph SDK 之一时，可以从环境变量中推断出该密钥。

默认情况下，自托管部署没有安全方案。这意味着它们只能部署在安全的网络上或带有身份验证的环境中。要添加自定义身份验证，请参阅如何添加自定义身份验证。

自定义安全方案

要在你的 OpenAPI 文档中自定义安全方案，请在 langgraph.json 的 auth 配置中添加一个 openapi 字段。请记住，这仅更新 API 文档——你还必须按照如何添加自定义身份验证中所示实现相应的身份验证逻辑。

请注意，LangGraph 平台不提供身份验证端点——你需要在客户端应用程序中处理用户身份验证，并将生成的凭证传递给 LangGraph API。

{
  "auth": {
    "path": "./auth.py:my_auth",  // 在此处实现身份验证逻辑
    "openapi": {
      "securitySchemes": {
        "OAuth2": {
          "type": "oauth2",
          "flows": {
            "implicit": {
              "authorizationUrl": "https://your-auth-server.com/oauth/authorize",
              "scopes": {
                "me": "读取当前用户的信息",
                "threads": "访问创建和管理线程的权限"
              }
            }
          }
        }
      },
      "security": [
        {"OAuth2": ["me", "threads"]}
      ]
    }
  }
}

{
  "auth": {
    "path": "./auth.py:my_auth",  // 在此处实现身份验证逻辑
    "openapi": {
      "securitySchemes": {
        "apiKeyAuth": {
          "type": "apiKey",
          "in": "header",
          "name": "X-API-Key"
        }
      },
      "security": [
        {"apiKeyAuth": []}
      ]
    }
  }
}

测试

更新配置后：

  1. 部署你的应用程序
  2. 访问 /docs 查看更新后的 OpenAPI 文档
  3. 使用来自认证服务器的凭证测试各个端点（确保你首先实现了认证逻辑）

Comments