开放 API

这是一个为 Better Auth 提供开放 API 参考的插件。它会展示所有由插件和核心添加的端点，同时也提供测试端点的方法。该插件使用 Scalar 来展示开放 API 参考。

安装

import { betterAuth } from "better-auth"
import { openAPI } from "better-auth/plugins"

export const auth = betterAuth({
    plugins: [
        openAPI(), 
    ]
})

使用

开放 API 参考使用 OpenAPI 3.1.1 规范生成。你可以使用该参考来生成客户端库、文档等更多内容。如果你将生成的 schema 与客户端生成器或其他工具一起使用，请确保它们支持 OpenAPI 3.1 语义。

生成的 Schema

若要以 JSON 格式直接获取生成的开放 API Schema，可以调用 auth.api.generateOpenAPISchema()，它将返回一个 JSON 格式的开放 API Schema。

import { auth } from "@/lib/auth"

const openAPISchema = await auth.api.generateOpenAPISchema()
console.log(openAPISchema)

在 Scalar 中使用多个来源

如果你使用 Scalar 来构建 API 文档，可以将 Better Auth 作为除主 API 外的额外数据来源：

当你使用 Hono 和 Scalar 来构建 OpenAPI 文档时，可以通过添加 Better Auth 作为来源来集成：

app.get("/docs", Scalar({
  pageTitle: "API Documentation", 
  sources: [
    { url: "/api/open-api", title: "API" },
    // Better Auth 架构生成端点
    { url: "/api/auth/open-api/generate-schema", title: "Auth" },
  ],
}));

配置

path - 开放 API 参考服务的路径。默认是 /api/auth/reference。你可以修改为你想要的任何路径，但请注意它会附加到你的认证服务器的基础路径上。

disableDefaultReference - 如果设置为 true，将禁用 Scalar 自带的默认开放 API 参考 UI。默认值为 false。

此设置允许你在一个统一的文档界面中同时展示你应用的 API 和 Better Auth 的认证端点。

theme - 允许你更改开放 API 参考页面的主题。默认是 default。

nonce - 允许你为内联脚本传递 nonce 字符串，以满足内容安全策略（CSP）的要求。默认值为 undefined。