跳到内容

在 OpenAPI 中文档化 API 认证

本指南介绍了如何为您的 LangGraph 平台 API 文档定制 OpenAPI 安全架构。一个良好文档化的安全架构有助于 API 消费者理解如何使用您的 API 进行认证，甚至可以实现客户端的自动生成。有关 LangGraph 认证系统的更多详细信息，请参阅认证与访问控制概念指南。

实现 vs 文档

本指南仅涵盖如何在 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",  // 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": []}
      ]
    }
  }
}

测试

更新配置后

  1. 部署您的应用程序
  2. 访问 /docs 查看更新的 OpenAPI 文档
  3. 使用您的认证服务器的凭据尝试这些端点（请确保您已首先实现认证逻辑）