Open API

이 플러그인은 Better Auth를 위한 Open API 참조를 제공합니다. 플러그인과 코어에 의해 추가된 모든 endpoint를 표시합니다. 또한 endpoint를 테스트하는 방법을 제공합니다. Scalar를 사용하여 Open API 참조를 표시합니다.

설치

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

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

사용법

Open API 참조는 OpenAPI 3.0 사양을 사용하여 생성됩니다. 참조를 사용하여 클라이언트 라이브러리, 문서 등을 생성할 수 있습니다.

참조는 Scalar 라이브러리를 사용하여 생성됩니다. Scalar는 endpoint를 보고 테스트하는 방법을 제공합니다. Try it out 버튼을 클릭하고 필요한 매개변수를 제공하여 endpoint를 테스트할 수 있습니다.

생성된 스키마

생성된 Open API 스키마를 JSON으로 직접 가져오려면 auth.api.generateOpenAPISchema()를 수행할 수 있습니다. 이렇게 하면 Open API 스키마가 JSON 객체로 반환됩니다.

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

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

여러 소스와 함께 Scalar 사용

API 문서에 Scalar를 사용하는 경우 주 API와 함께 Better Auth를 추가 소스로 추가할 수 있습니다:

Hono와 함께 Scalar를 OpenAPI 문서에 사용할 때 Better Auth를 소스로 추가하여 통합할 수 있습니다:

app.get("/docs", Scalar({
  pageTitle: "API Documentation",
  sources: [
    { url: "/api/open-api", title: "API" },
    // Better Auth 스키마 생성 endpoint
    { url: "/api/auth/open-api/generate-schema", title: "Auth" },
  ],
}));

구성

path - Open API 참조가 제공되는 경로입니다. 기본값은 /api/auth/reference입니다. 원하는 경로로 변경할 수 있지만 auth 서버의 기본 경로에 추가된다는 점에 유의하세요.

disableDefaultReference - true로 설정하면 Scalar에 의한 기본 Open API 참조 UI가 비활성화됩니다. 기본값은 false입니다.

이를 통해 애플리케이션의 API와 Better Auth의 인증 endpoint를 통합 문서 인터페이스에 모두 표시할 수 있습니다.

theme - OpenAPI 참조 페이지의 테마를 변경할 수 있습니다. 기본값은 default입니다.