在 OpenAPI 中记录 API 认证

本指南展示了如何为您的 LangSmith API 文档自定义 OpenAPI 安全模式。一个文档完善的安全模式有助于 API 使用者理解如何对您的 API 进行身份验证，甚至支持自动生成客户端。有关 LangGraph 认证系统的更多详细信息，请参阅认证与访问控制概念指南。

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

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

默认模式

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

LangSmith

默认情况下，LangSmith 要求在 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 文档——您还必须实现相应的认证逻辑，如如何添加自定义认证中所示。

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

OAuth2 与 Bearer Token

{
  "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"]}
      ]
    }
  }
}

API 密钥

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

测试

更新配置后：

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

---

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.