在 OpenAPI 中记录 API 认证

本指南介绍如何为 LangSmith API 文档自定义 OpenAPI 安全模式。良好的安全模式文档能帮助 API 使用者了解如何通过 API 进行认证，甚至支持自动生成客户端。有关 LangGraph 认证系统的更多详细信息，请参阅认证与访问控制概念指南。

NOTE

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

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

默认模式

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

默认情况下，LangSmith 要求在 x-api-key 请求头中提供 LangSmith API key：

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

使用任一 LangGraph SDK 时，可以从环境变量中推断此信息。

默认情况下，自托管部署没有安全方案。这意味着它们只应部署在受保护的网络中，或启用认证。要添加自定义认证，请参阅如何添加自定义认证。

自定义安全模式

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

请注意，LangSmith 不提供认证端点——你需要在客户端应用中处理用户认证，并将生成的凭据传递给 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"]}
      ]
    }
  }
}

测试

更新配置后：

1. 部署你的应用
2. 访问 /docs 查看更新后的 OpenAPI 文档
3. 使用认证服务器提供的凭据试用端点（请确保先实现认证逻辑）

---