# 开放 API (/docs/plugins/open-api)

Better Auth 的开放 API 参考。





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

<Callout>
  该插件仍处于开发初期。我们正在为其添加更多功能并填补空白。
</Callout>

## 安装 [#安装]

<Steps>
  <Step>
    ### 在 **auth** 配置中添加插件 [#在-auth-配置中添加插件]

    ```ts title="auth.ts"
    import { betterAuth } from "better-auth"
    import { openAPI } from "better-auth/plugins" // [!code highlight]

    export const auth = betterAuth({
        plugins: [
            openAPI(), // [!code highlight]
        ]
    })
    ```
  </Step>

  <Step>
    ### 访问 `/api/auth/reference` 查看开放 API 参考 [#访问-apiauthreference-查看开放-api-参考]

    每个插件的端点会按插件名称分组。核心端点会归到 `Default` 组下。模型架构会归到 `Models` 组下。

        <img alt="开放 API 参考" src="__img0" />
  </Step>
</Steps>

## 使用 [#使用]

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

### 生成的 Schema [#生成的-schema]

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

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

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

### 在 Scalar 中使用多个来源 [#在-scalar-中使用多个来源]

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

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

```ts
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\`\`。