Merge better-auth schema #3782

abbbdab · 2025-11-13T00:51:15Z

abbbdab
Nov 13, 2025

Better-Auth has been brilliant, but I hate the fact that I have two openAPI schemas / Scalar instances in the project. Since there is no easy way to merge it, and the inbuilt openAPI and scalar options in config file don't really accept Scalar configuration option, I found this workaround to serve the merged API specs.

It's still rudimentary and I did it quickly. Will be cleaning it up soon.

`import { defineEventHandler, getRequestURL, setResponseHeader } from "h3";
import { auth } from "../utils/auth";

export default defineEventHandler(async (event) => {
const url = getRequestURL(event);
const baseUrl = ${url.protocol}//${url.host};

// Get Nitro's OpenAPI schema
const nitroOpenAPI: any = await $fetch(`${baseUrl}/openapi.json`);

// Get better-auth OpenAPI schema
// @ts-ignore - accessing the client's generateOpenAPISchema method
const betterAuthOpenAPI: any = await auth.api.generateOpenAPISchema();


// Merge the schemas
const mergedOpenAPI = {
    openapi: "3.1.0",
    info: {
        title: "API Documentation",
        description: "Combined API documentation for application including authentication endpoints",
        version: "1.0.0"
    },
    servers: nitroOpenAPI.servers || [{ url: baseUrl }],
    tags: [
        { name: "Authentication", description: "Authentication and user management endpoints" },
        ...(nitroOpenAPI.tags || [])
    ],
    paths: {
        ...nitroOpenAPI.paths,
        ...Object.fromEntries(
            Object.entries(betterAuthOpenAPI.paths || {}).map(([path, methods]: [string, any]) => {
                // Replace existing tags with only "Authentication" tag
                const updatedMethods = Object.fromEntries(
                    Object.entries(methods).map(([method, config]: [string, any]) => [
                        method,
                        {
                            ...config,
                            tags: ['Authentication']
                        }
                    ])
                );
                return [`/api/auth${path}`, updatedMethods];
            })
        )
    },
    components: {
        schemas: {
            ...(nitroOpenAPI.components?.schemas || {}),
            ...(betterAuthOpenAPI.components?.schemas || {})
        },
        securitySchemes: {
            ...(nitroOpenAPI.components?.securitySchemes || {}),
            ...(betterAuthOpenAPI.components?.securitySchemes || {})
        }
    }
};

// Set response header for HTML content
setResponseHeader(event, "Content-Type", "text/html");


const specJson = JSON.stringify(mergedOpenAPI);

return <!doctype html><html><head><title> API Documentation</title><meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" /></head><body><script id="api-reference" type="application/json">${specJson}</script><script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script></body</html>});`

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Merge better-auth schema #3782

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Uh oh!

Merge better-auth schema #3782

Uh oh!

Uh oh!

abbbdab Nov 13, 2025

Replies: 0 comments

abbbdab
Nov 13, 2025