openapi doc in doc site

Author: Rajat

apps/docs/app/(home)/[[...slug]]/page.tsx

@@ -7,17 +7,15 @@ import {
 } from "fumadocs-ui/page";
 import { createRelativeLink } from "fumadocs-ui/mdx";
 import { notFound, redirect } from "next/navigation";
+import { APIPage } from "@/components/api-page";
 import { getMDXComponents } from "@/mdx-components";
 
-const API_REFERENCE_INDEX = "/api-reference/listContacts";
+const API_REFERENCE_INDEX = "/api-reference/contacts/get";
 
 export default async function Page(props: {
     params: Promise<{ slug?: string[] }>;
 }) {
     const params = await props.params;
-    process.stderr.write(
-        `Rendering docs slug: ${(params.slug ?? []).join("/") || "index"}\n`,
-    );
     const slugPath = params.slug?.join("/");
 
     if (slugPath === "api-reference" || slugPath === "rest-api") {
@@ -27,6 +25,18 @@ export default async function Page(props: {
     const page = source.getPage(params.slug);
     if (!page) notFound();
 
+    if (page.data.type === "openapi") {
+        return (
+            <DocsPage full>
+                <DocsTitle>{page.data.title}</DocsTitle>
+                <DocsDescription>{page.data.description}</DocsDescription>
+                <DocsBody>
+                    <APIPage {...page.data.getAPIPageProps()} />
+                </DocsBody>
+            </DocsPage>
+        );
+    }
+
     const MDXContent = page.data.body;
 
     return (
@@ -54,7 +64,12 @@ export async function generateStaticParams() {
     }
     const bySlug = new Map<string, { slug?: string[] }>();
 
-    for (const param of [{ slug: [] as string[] }, ...params]) {
+    for (const param of [
+        { slug: [] as string[] },
+        ...params,
+        { slug: ["api-reference"] },
+        { slug: ["rest-api"] },
+    ]) {
         bySlug.set((param.slug ?? []).join("/"), param);
     }
 

apps/docs/lib/openapi.ts

@@ -24,58 +24,60 @@ const openApiDocument = generateOpenApi(
         tags: [
             {
                 name: "Contacts",
-                description: "Manage contacts and segmentation.",
+                description: "Manage contacts (subscribers).",
+            },
+            {
+                name: "Segments",
+                description:
+                    "Saved, named, reusable contact filters - build a filter once, reuse it across broadcasts and sequences.",
             },
             { name: "Templates", description: "Reusable email templates." },
             {
                 name: "Sequences",
                 description:
-                    "Broadcasts and multi-step, event-triggered sequences.",
+                    "Broadcasts (one-off) and sequences (multi-step, event-triggered).",
             },
             {
                 name: "Settings",
                 description:
-                    "Per-team settings, including SMTP configuration and test sends.",
+                    "Per-team settings, including email sending provider (SMTP) configuration and test sends.",
             },
             {
                 name: "Teams",
                 description:
-                    "Team management, API keys, and server-to-server provisioning.",
+                    "Team management (list/create/rename/delete), per-team API keys, and server-to-server provisioning.",
             },
         ],
         components: {
             securitySchemes: {
-                OAuth2: {
-                    type: "oauth2",
-                    flows: {
-                        authorizationCode: {
-                            authorizationUrl: "/oauth/authorize",
-                            tokenUrl: "/oauth/token",
-                            scopes: {},
-                        },
-                    },
-                },
                 apiKeyAuth: {
                     type: "apiKey",
                     in: "header",
                     name: "x-sendlit-apikey",
                 },
+                bearerAuth: {
+                    type: "http",
+                    scheme: "bearer",
+                    bearerFormat: "JWT",
+                },
                 provisioningSecretAuth: {
                     type: "apiKey",
                     in: "header",
                     name: "X-Sendlit-Provisioning-Secret",
                 },
             },
         },
-        security: [{ OAuth2: [] }, { apiKeyAuth: [] }],
+        security: [{ apiKeyAuth: [] }, { bearerAuth: [] }],
     },
     {
-        setOperationId: true,
         operationMapper: (operation, route) => {
             const path = (route as { path?: string }).path;
 
             return {
                 ...operation,
+                tags: (route.metadata as { tag?: string } | undefined)?.tag
+                    ? [(route.metadata as { tag: string }).tag]
+                    : operation.tags,
                 security:
                     path === "/provisioning/teams"
                         ? [{ provisioningSecretAuth: [] }]

apps/docs/lib/source.ts

@@ -1,11 +1,21 @@
 import { createElement } from "react";
 import { icons } from "lucide-react";
-import { loader } from "fumadocs-core/source";
+import { loader, multiple } from "fumadocs-core/source";
+import { openapiPlugin, openapiSource } from "fumadocs-openapi/server";
 import { docs } from "../.source/server";
+import { openapi } from "@/lib/openapi";
+
+const apiSource: any = await openapiSource(openapi, {
+    baseDir: "api-reference",
+});
 
 export const source: any = loader({
     baseUrl: "/",
-    source: docs.toFumadocsSource() as any,
+    source: multiple({
+        docs: docs.toFumadocsSource() as any,
+        openapi: apiSource,
+    }) as any,
+    plugins: [openapiPlugin()],
     icon(icon) {
         if (icon && icon in icons) {
             return createElement(icons[icon as keyof typeof icons]);