如何在 OpenAPI 中记录 API 身份验证¶

本指南展示了如何为您的 LangGraph Platform API 文档自定义 OpenAPI 安全 schema。一个良好记录的安全 schema 帮助 API 使用者理解如何使用您的 API 进行身份验证，甚至可以实现自动客户端生成。有关 LangGraph 身份验证系统的更多详细信息，请参阅身份验证和访问控制概念指南。

实现 vs 文档

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

本指南适用于所有 LangGraph Platform 部署（云、BYOC 和自托管）。如果您未使用 LangGraph Platform，则本指南不适用于 LangGraph 开源库的用法。

默认 Schema¶

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

LangGraph 云

默认情况下，LangGraph 云需要 x-api-key 标头中的 LangSmith API 密钥

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

当使用 LangGraph SDK 之一时，这可以从环境变量中推断出来。

自托管

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

自定义安全 Schema¶

要自定义 OpenAPI 文档中的安全 schema，请在 langgraph.json 中的 auth 配置中添加 openapi 字段。请记住，这只会更新 API 文档 - 您还必须实现相应的身份验证逻辑，如如何添加自定义身份验证所示。

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

带有 Bearer Token 的 OAuth2API 密钥

{
  "auth": {
    "path": "./auth.py:my_auth",  // Implement auth logic here
    "openapi": {
      "securitySchemes": {
        "OAuth2": {
          "type": "oauth2",
          "flows": {
            "implicit": {
              "authorizationUrl": "https://your-auth-server.com/oauth/authorize",
              "scopes": {
                "me": "Read information about the current user",
                "threads": "Access to create and manage threads"
              }
            }
          }
        }
      },
      "security": [
        {"OAuth2": ["me", "threads"]}
      ]
    }
  }
}

{
  "auth": {
    "path": "./auth.py:my_auth",  // Implement auth logic here
    "openapi": {
      "securitySchemes": {
        "apiKeyAuth": {
          "type": "apiKey",
          "in": "header",
          "name": "X-API-Key"
        }
      },
      "security": [
        {"apiKeyAuth": []}
      ]
    }
  }
}

测试¶

更新配置后

部署您的应用程序
访问 /docs 以查看更新后的 OpenAPI 文档
使用来自您的身份验证服务器的凭据试用端点（确保您已首先实现身份验证逻辑）

如何在 OpenAPI 中记录 API 身份验证¶

默认 Schema¶

自定义安全 Schema¶

测试¶

评论