fumadocs-openapi 3.1.0 → 3.1.2

package/dist/index.d.ts

@@ -55,7 +55,9 @@ interface GenerateOptions {
         from: string;
     }[];
     /**
-     * Customise frontmatter
+     * Customise frontmatter.
+     *
+     * A `full: true` property will be added by default.
      */
     frontmatter?: (title: string, description: string | undefined) => Record<string, unknown>;
     renderer?: Partial<Renderer>;
@@ -64,7 +66,12 @@ interface GenerateTagOutput {
     tag: string;
     content: string;
 }
+interface GenerateOperationOutput {
+    id: string;
+    content: string;
+}
 declare function generate(pathOrDocument: string | OpenAPIV3.Document, options?: GenerateOptions): Promise<string>;
+declare function generateOperations(pathOrDocument: string | OpenAPIV3.Document, options?: GenerateOptions): Promise<GenerateOperationOutput[]>;
 declare function generateTags(pathOrDocument: string | OpenAPIV3.Document, options?: GenerateOptions): Promise<GenerateTagOutput[]>;
 
 interface Config extends GenerateOptions {
@@ -83,7 +90,7 @@ interface Config extends GenerateOptions {
      *
      * @defaultValue file
      */
-    per?: 'tag' | 'file';
+    per?: 'tag' | 'file' | 'operation';
     /**
      * Specify name for output file
      */
@@ -110,4 +117,4 @@ interface RenderContext {
 
 declare function createElement(name: string, props: object, ...child: string[]): string;
 
-export { type APIInfoProps, type Config, type GenerateOptions, type GenerateTagOutput, type MethodInformation, type ObjectCollapsibleProps, type PropertyProps, type RenderContext, type Renderer, type RequestProps, type ResponseProps, type ResponsesProps, type RouteInformation, createElement, defaultRenderer, generate, generateFiles, generateTags };
+export { type APIInfoProps, type Config, type GenerateOperationOutput, type GenerateOptions, type GenerateTagOutput, type MethodInformation, type ObjectCollapsibleProps, type PropertyProps, type RenderContext, type Renderer, type RequestProps, type ResponseProps, type ResponsesProps, type RouteInformation, createElement, defaultRenderer, generate, generateFiles, generateOperations, generateTags };

package/dist/index.js

@@ -72,6 +72,9 @@ function codeblock({ language, title }, child) {
     "```"
   ].join("\n");
 }
+function heading(depth, child) {
+  return `${"#".repeat(depth)} ${child.trim()}`;
+}
 
 // src/render/renderer.ts
 var defaultRenderer = {
@@ -99,6 +102,7 @@ function renderPage(title, description, content, options) {
   const banner = dump({
     title,
     description,
+    full: true,
     ...options.frontmatter?.(title, description)
   }).trim();
   const finalImports = (options.imports ?? [
@@ -375,23 +379,27 @@ function getSchemaType(schema) {
 }
 
 // src/render/operation.ts
-async function renderOperation(path, method, ctx) {
+async function renderOperation(path, method, ctx, noTitle = false) {
+  let level = 2;
   const body = noRef(method.requestBody);
   const security = method.security ?? ctx.document.security;
   const info = [];
   const example = [];
   const title = method.summary ?? method.operationId;
-  if (title) info.push(`## ${title}`);
+  if (title && !noTitle) {
+    info.push(heading(level, title));
+    level++;
+  }
   if (method.description) info.push(p(method.description));
   if (security) {
-    info.push("### Authorization");
+    info.push(heading(level, "Authorization"));
     info.push(getAuthSection(security, ctx));
   }
   if (body) {
     const bodySchema = getPreferredMedia(body.content)?.schema;
     if (!bodySchema) throw new Error();
     info.push(
-      `### Request Body${!body.required ? " (Optional)" : ""}`,
+      heading(level, `Request Body ${!body.required ? "(Optional)" : ""}`),
       p(body.description),
       schemaElement("body", noRef(bodySchema), {
         parseObject: true,
@@ -435,7 +443,7 @@ async function renderOperation(path, method, ctx) {
     parameterGroups.set(groupName, group);
   }
   for (const [group, parameters] of Array.from(parameterGroups.entries())) {
-    info.push(`### ${group}`, ...parameters);
+    info.push(heading(level, group), ...parameters);
   }
   info.push(getResponseTable(method));
   example.push(
@@ -584,6 +592,29 @@ async function generate(pathOrDocument, options = {}) {
     options
   );
 }
+async function generateOperations(pathOrDocument, options = {}) {
+  const document = await Parser.dereference(pathOrDocument);
+  const routes = buildRoutes(document).get("all") ?? [];
+  const ctx = getContext(document, options);
+  return await Promise.all(
+    routes.flatMap((route) => {
+      return route.methods.map(async (method) => {
+        const content = renderPage(
+          method.summary ?? method.method,
+          method.description,
+          [await renderOperation(route.path, method, ctx, true)],
+          options
+        );
+        if (!method.operationId)
+          throw new Error("Operation ID is required for generating docs.");
+        return {
+          id: method.operationId,
+          content
+        };
+      });
+    })
+  );
+}
 async function generateTags(pathOrDocument, options = {}) {
   const document = await Parser.dereference(pathOrDocument);
   const tags = Array.from(buildRoutes(document).entries());
@@ -640,10 +671,24 @@ async function generateFiles({
         console.log(`Generated: ${outPath}`);
         return;
       }
+      if (per === "operation") {
+        const results2 = await generateOperations(path, options);
+        await Promise.all(
+          results2.map(async (result) => {
+            const outPath = join(
+              outputDir,
+              filename,
+              `${getName(result.id)}.mdx`
+            );
+            await write(outPath, result.content);
+            console.log(`Generated: ${outPath}`);
+          })
+        );
+      }
       const results = await generateTags(path, options);
       for (const result of results) {
         let tagName = result.tag;
-        tagName = nameFn?.("tag", tagName) ?? tagName.toLowerCase().replace(/\s+/g, "-");
+        tagName = nameFn?.("tag", tagName) ?? getName(tagName);
         const outPath = join(outputDir, filename, `${tagName}.mdx`);
         await write(outPath, result.content);
         console.log(`Generated: ${outPath}`);
@@ -651,6 +696,12 @@ async function generateFiles({
     })
   );
 }
+function getName(s) {
+  return s.replace(
+    /[A-Z]/g,
+    (match, idx) => idx === 0 ? match : `-${match.toLowerCase()}`
+  ).replace(/\s+/g, "-").toLowerCase();
+}
 async function write(path, content) {
   await mkdir(dirname(path), { recursive: true });
   await writeFile(path, content);
@@ -660,5 +711,6 @@ export {
   defaultRenderer,
   generate,
   generateFiles,
+  generateOperations,
   generateTags
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fumadocs-openapi",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "description": "Generate MDX docs for your OpenAPI spec",
   "keywords": [
     "NextJs",