Skip to content

如何在OpenAPI中记录API认证

本指南展示了如何为您的LangGraph平台API文档自定义OpenAPI安全模式。一个详尽的安全模式文档有助于API消费者理解如何与您的API进行身份验证，并且甚至可以启用自动客户端生成。有关LangGraph认证系统的更多细节，请参阅认证与访问控制概念指南。

实现与文档的区别

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

本指南适用于所有LangGraph平台部署（云、自带运行环境和自托管）。如果您不使用LangGraph平台，则本指南不适用于LangGraph开源库的使用。

默认安全方案

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

默认情况下，LangGraph Cloud 要求在 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