开放 API

这是一个为 Better Auth 提供开放 API 参考的插件。它显示了插件和核心添加的所有端点。它还提供了一种测试端点的方法。它使用 Scalar 来显示开放 API 参考。

【This is a plugin that provides an Open API reference for Better Auth. It shows all endpoints added by plugins and the core. It also provides a way to test the endpoints. It uses Scalar to display the Open API reference.】

安装

【Installation】

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

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

用法

【Usage】

开放 API 参考是使用 OpenAPI 3.0 规范生成的。你可以使用该参考来生成客户端库、文档等。

【The Open API reference is generated using the OpenAPI 3.0 specification. You can use the reference to generate client libraries, documentation, and more.】

参考文献是使用 Scalar 库生成的。Scalar 提供了一种查看和测试端点的方法。你可以通过点击 Try it out 按钮并提供所需的参数来测试这些端点。

【The reference is generated using the Scalar library. Scalar provides a way to view and test the endpoints. You can test the endpoints by clicking on the Try it out button and providing the required parameters.】

生成的模式

【Generated Schema】

要直接以 JSON 获取生成的 Open API 模式，你可以使用 auth.api.generateOpenAPISchema()。这将返回一个 JSON 对象形式的 Open API 模式。

【To get the generated Open API schema directly as JSON, you can do auth.api.generateOpenAPISchema(). This will return the Open API schema as a JSON object.】

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

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

使用 Scalar 与多个源

【Using Scalar with Multiple Sources】

如果你正在使用 Scalar 进行 API 文档编写，你可以将 Better Auth 作为主要 API 之外的额外来源添加进去：

【If you're using Scalar for your API documentation, you can add Better Auth as an additional source alongside your main API:】

在将 Hono 与 Scalar 一起用于 OpenAPI 文档时，你可以通过将 Better Auth 添加为源来进行集成：

【When using Hono with Scalar for OpenAPI documentation, you can integrate Better Auth by adding it as a source:】

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" },
  ],
}));

配置

【Configuration】

path - 提供 Open API 参考的路径。默认是 /api/auth/reference。你可以将其更改为你喜欢的任何路径，但请注意，它会附加到你的认证服务器的基础路径上。

disableDefaultReference - 如果设置为 true，Scalar 提供的默认 Open API 引用界面将被禁用。默认值为 false。

这使你可以在统一的文档界面中显示你应用的 API 和 Better Auth 的认证端点。

【This allows you to display both your application's API and Better Auth's authentication endpoints in a unified documentation interface.】

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

nonce - 允许你向内联脚本传递一个 nonce 字符串，以符合内容安全策略（CSP）。默认值为 undefined。