开放 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 按钮并提供所需参数来测试端点。

生成的架构

要直接获取生成的开放 API 架构作为 JSON，您可以执行 auth.api.generateOpenAPISchema()。这将返回开放 API 架构作为 JSON 对象。

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 generation endpoint
    { url: "/api/auth/open-api/generate-schema", title: "Auth" },
  ],
}));

配置

path - 开放 API 参考所服务的路径。默认为 /api/auth/reference。您可以将其更改为您喜欢的任何路径，但请记住，它将被追加到您的 auth 服务器的基路径。

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

这允许您在统一的文档界面中显示您的应用程序 API 和 Better Auth 的认证端点。

theme - 允许您更改 OpenAPI 参考页面的主题。默认为 default。