开放 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.0 规范生成。你可以使用该参考来生成客户端库、文档等。

该参考使用 Scalar 库生成。Scalar 提供了查看和测试端点的方式。你可以点击 Try it out 按钮并填写所需参数来测试端点。

生成的 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 schema 生成端点
    { 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。