A modern and easy to use dashboard. 80+ integrations. 20K+ icons built in. Authentication out of the box. No YAML, drag and drop configuration.
import type { apiSource } from "@/lib/openapi";
type ApiPage = ReturnType<typeof apiSource.getPages>[number];
type UnknownRecord = Record<string, unknown>;
function record(value: unknown): UnknownRecord | undefined {
if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
return value as UnknownRecord;
}
function resolveReferences(value: unknown, document: UnknownRecord, seen = new Set<string>()): unknown {
if (Array.isArray(value)) return value.map((item) => resolveReferences(item, document, seen));
const current = record(value);
if (!current) return value;
const referenceValue = current.$ref;
if (typeof referenceValue !== "string" || !referenceValue.startsWith("#/")) {
return Object.fromEntries(
Object.entries(current).map(([key, item]) => [key, resolveReferences(item, document, seen)]),
);
}
const reference = referenceValue;
if (seen.has(reference)) return { $ref: reference };
let target: unknown = document;
for (const segment of reference.slice(2).split("/")) {
const parent = record(target);
target = parent?.[segment.replaceAll("~1", "/").replaceAll("~0", "~")];
}
if (target === undefined) return current;
const nextSeen = new Set(seen).add(reference);
const resolved = record(resolveReferences(target, document, nextSeen));
if (!resolved) return target;
const siblings = Object.fromEntries(
Object.entries(current)
.filter(([key]) => key !== "$ref")
.map(([key, item]) => [key, resolveReferences(item, document, nextSeen)]),
);
return { ...resolved, ...siblings };
}
function formatSchema(value: unknown): string {
if (value === undefined) return "";
return `\n\`\`\`json\n${JSON.stringify(value, null, 2)}\n\`\`\``;
}
function renderParameters(parameters: unknown, document: UnknownRecord): string {
if (!Array.isArray(parameters) || parameters.length === 0) return "";
const rows = parameters.flatMap((value) => {
const parameter = record(resolveReferences(value, document));
if (!parameter) return [];
const schema = record(parameter.schema);
let type = "object";
if (typeof schema?.type === "string") type = schema.type;
let required = "";
if (parameter.required === true) required = " (required)";
let description = "";
if (typeof parameter.description === "string") description = ` — ${parameter.description}`;
let location = "parameter";
if (typeof parameter.in === "string") location = parameter.in;
let name = "unknown";
if (typeof parameter.name === "string") name = parameter.name;
return [
`- \`${name}\` (${location}, ${type}${required})${description}${formatSchema(resolveReferences(parameter.schema, document))}`,
];
});
if (rows.length === 0) return "";
return `\n### Parameters\n\n${rows.join("\n")}`;
}
function renderRequestBody(requestBody: unknown, document: UnknownRecord): string {
const body = record(resolveReferences(requestBody, document));
const content = record(body?.content);
if (!content) return "";
const parts = Object.entries(content).flatMap(([mediaType, mediaValue]) => {
const media = record(mediaValue);
if (!media) return [];
const schema = resolveReferences(media.schema, document);
const example = media.example;
const examples = record(media.examples);
let exampleText = formatSchema(example);
if (example === undefined && examples) exampleText = formatSchema(examples);
return [`#### ${mediaType}${formatSchema(schema)}${exampleText}`];
});
if (parts.length === 0) return "";
let description = "";
if (typeof body?.description === "string") description = `${body.description}\n\n`;
let required = "";
if (body?.required === true) required = " Required.";
return `\n### Request body\n\n${description}${required}\n${parts.join("\n\n")}`;
}
function renderResponses(responses: unknown, document: UnknownRecord): string {
const entries = record(resolveReferences(responses, document));
if (!entries) return "";
const parts = Object.entries(entries).flatMap(([status, value]) => {
const response = record(value);
if (!response) return [];
let description = "";
if (typeof response.description === "string") description = response.description;
const content = record(response.content);
let schemas: string[] = [];
if (content) {
schemas = Object.entries(content).flatMap(([mediaType, mediaValue]) => {
const media = record(mediaValue);
if (!media) return [];
return [
`\n${mediaType}${formatSchema(resolveReferences(media.schema, document))}${formatSchema(media.example)}`,
];
});
}
let heading = `#### ${status}`;
if (description) heading += ` — ${description}`;
return [`${heading}${schemas.join("\n")}`];
});
if (parts.length === 0) return "";
return `\n### Responses\n\n${parts.join("\n\n")}`;
}
/** Render one generated OpenAPI page as portable Markdown for search and LLM exports. */
export function getApiMarkdown(page: ApiPage): string {
const props = page.data.getOpenAPIPageProps();
const schema = record(page.data.getSchema().bundled);
const paths = record(schema?.paths);
const operations = props.operations ?? [];
let pageDescription = "";
if (page.data.description) pageDescription = `${page.data.description}\n\n`;
const rendered = operations.flatMap(({ path, method }) => {
const pathItem = record(paths?.[path]);
const operation = record(resolveReferences(pathItem?.[method], schema ?? {}));
if (!operation) return [];
let operationId: string | undefined;
if (typeof operation.operationId === "string") operationId = operation.operationId;
let title = operationId ?? `${method.toUpperCase()} ${path}`;
if (typeof operation.summary === "string") title = operation.summary;
let description = "";
if (typeof operation.description === "string") description = `${operation.description}\n\n`;
const parameters = [...arrayValue(pathItem?.parameters), ...arrayValue(operation.parameters)];
const security = operation.security ?? schema?.security;
const components = record(schema?.components);
const schemes = record(components?.securitySchemes);
let authenticationOptional = false;
let authLines: string[] = [];
if (Array.isArray(security)) {
authLines = security.flatMap((requirement) => {
const names = record(requirement);
if (!names) return [];
if (Object.keys(names).length === 0) authenticationOptional = true;
return Object.keys(names).flatMap((name) => {
const scheme = record(resolveReferences(schemes?.[name], schema ?? {}));
if (!scheme) return [];
let location = "authorization";
if (typeof scheme.in === "string") location = scheme.in;
let keyName = name;
if (typeof scheme.name === "string") keyName = scheme.name;
let schemeDescription = "";
if (typeof scheme.description === "string") schemeDescription = ` — ${scheme.description}`;
return [`- ${keyName} (${location})${schemeDescription}`];
});
});
}
let auth = "";
if (authLines.length > 0) {
let heading = "### Authentication";
if (authenticationOptional) heading += " (optional)";
auth = `\n${heading}\n\n${authLines.join("\n")}\n`;
}
let heading = `## ${title}\n\n\`${method.toUpperCase()} ${path}\``;
if (operationId) heading += `\n\nOperation ID: \`${operationId}\``;
return [
`${heading}\n\n${description}${auth}${renderParameters(parameters, schema ?? {})}${renderRequestBody(operation.requestBody, schema ?? {})}${renderResponses(operation.responses, schema ?? {})}`,
];
});
const serverGuidance =
"Set Server URL to the full URL of your Homarr instance, including its scheme and reverse-proxy path. Open Test, then select Send to run a request from your browser; authentication values are not persisted.\n\n";
return `# ${page.data.title}\n\n${pageDescription}${serverGuidance}${rendered.join("\n\n")}`.trim();
}
export function getApiMarkdownUrl(page: ApiPage) {
const segments = [...page.url.replace(/^\/api-reference\/?/, "").split("/"), "content.md"];
return {
segments,
url: `/llms.mdx${page.url}/content.md`,
};
}
function arrayValue(value: unknown) {
if (Array.isArray(value)) return value;
return [];
}