fumadocs-openapi 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Fuma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/bin.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bin.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import {
+  generateFiles
+} from "./chunk-6NCGY6WV.js";
+
+// src/bin.ts
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+async function main() {
+  const configName = process.argv[2];
+  const config = await readConfig(configName);
+  await generateFiles(config);
+}
+async function readConfig(name = "openapi.config.js") {
+  const path = resolve(process.cwd(), name);
+  const result = await import(pathToFileURL(path).toString());
+  if (typeof result.default !== "object")
+    throw new Error("Invalid configuration");
+  return result.default;
+}
+void main();

package/dist/chunk-6NCGY6WV.js

@@ -0,0 +1,539 @@
+// src/generate.ts
+import Parser from "@apidevtools/swagger-parser";
+
+// src/render/element.ts
+function createElement(name, props, ...child) {
+  const s = [];
+  const params = Object.entries(props).map(([key, value]) => `${key}={${JSON.stringify(value)}}`).join(" ");
+  s.push(params.length > 0 ? `<${name} ${params}>` : `<${name}>`);
+  s.push(...child);
+  s.push(`</${name}>`);
+  return s.join("\n\n");
+}
+function p(child) {
+  if (!child)
+    return "";
+  return child.replace("<", "\\<").replace(">", "\\>");
+}
+function span(child) {
+  return `<span>${p(child)}</span>`;
+}
+function codeblock({ language, title }, child) {
+  return [
+    title ? `\`\`\`${language} title=${JSON.stringify(title)}` : `\`\`\`${language}`,
+    child,
+    "```"
+  ].join("\n");
+}
+
+// src/render/custom.ts
+function api(...child) {
+  return createElement("API", {}, ...child);
+}
+function apiExample(...child) {
+  return createElement("APIExample", {}, ...child);
+}
+function root(...child) {
+  return createElement("Root", {}, ...child);
+}
+function apiInfo(props, ...child) {
+  return createElement("APIInfo", props, ...child);
+}
+function accordions(...child) {
+  return createElement("Accordions", {}, ...child);
+}
+function accordion(props, ...child) {
+  return createElement("Accordion", props, ...child);
+}
+function tabs(props, ...child) {
+  return createElement("Tabs", props, ...child);
+}
+function tab(props, ...child) {
+  return createElement("Tab", props, ...child);
+}
+function property({ required = false, deprecated = false, ...props }, ...child) {
+  return createElement(
+    "Property",
+    { required, deprecated, ...props },
+    ...child
+  );
+}
+
+// src/samples/index.ts
+import { sample } from "openapi-sampler";
+
+// src/utils.ts
+function noRef(v) {
+  return v;
+}
+function getPreferredMedia(body) {
+  if (Object.keys(body).length === 0)
+    return void 0;
+  if ("application/json" in body)
+    return body["application/json"];
+  return Object.values(body)[0];
+}
+function getValue(value) {
+  return typeof value === "string" ? value : JSON.stringify(value, null, 2);
+}
+
+// src/samples/index.ts
+function createEndpoint(path, method, baseUrl = "https://example.com") {
+  const params = [];
+  const responses = {};
+  for (const param of method.parameters) {
+    const schema = noRef(
+      param.schema ?? getPreferredMedia(param.content ?? {})?.schema
+    );
+    if (!schema)
+      continue;
+    params.push({
+      name: param.name,
+      in: param.in,
+      schema
+    });
+  }
+  const body = noRef(method.requestBody)?.content ?? {};
+  const bodySchema = noRef(getPreferredMedia(body)?.schema);
+  for (const [code, value] of Object.entries(method.responses)) {
+    const mediaTypes = noRef(value).content ?? {};
+    const responseSchema = noRef(getPreferredMedia(mediaTypes)?.schema);
+    if (!responseSchema)
+      continue;
+    responses[code] = {
+      schema: responseSchema
+    };
+  }
+  let pathWithParameters = path;
+  const queryParams = new URLSearchParams();
+  for (const param of params) {
+    const value = generateSample(method.method, param.schema);
+    if (param.in === "query")
+      queryParams.append(param.name, getValue(value));
+    if (param.in === "path")
+      pathWithParameters = pathWithParameters.replace(
+        `{${param.name}}`,
+        getValue(value)
+      );
+  }
+  return {
+    url: new URL(pathWithParameters, baseUrl).toString(),
+    body: bodySchema ? generateSample(method.method, bodySchema) : void 0,
+    responses,
+    method: method.method,
+    parameters: params
+  };
+}
+function generateSample(method, schema) {
+  return sample(schema, {
+    skipReadOnly: method !== "GET",
+    skipWriteOnly: method === "GET"
+  });
+}
+
+// src/samples/response.ts
+function getExampleResponse(endpoint, code) {
+  if (code in endpoint.responses) {
+    const value = generateSample(
+      endpoint.method,
+      endpoint.responses[code].schema
+    );
+    return JSON.stringify(value, null, 2);
+  }
+}
+
+// src/samples/typescript.ts
+import { compile } from "json-schema-to-typescript";
+async function getTypescript(endpoint, code) {
+  if (code in endpoint.responses) {
+    return compile(endpoint.responses[code].schema, "Response", {
+      bannerComment: "",
+      additionalProperties: false,
+      format: true,
+      enableConstEnums: false
+    });
+  }
+}
+
+// src/samples/curl.ts
+function getSampleRequest(endpoint) {
+  const s = [];
+  s.push(`curl -X ${endpoint.method} "${endpoint.url}"`);
+  for (const param of endpoint.parameters) {
+    if (param.in === "header") {
+      const value = generateSample(endpoint.method, param.schema);
+      const header = `${param.name}: ${getValue2(value)}`;
+      s.push(`-H "${header}"`);
+    }
+    if (param.in === "formData") {
+      console.log("Request example for form data is not supported");
+    }
+  }
+  if (endpoint.body)
+    s.push(`-d '${getValue2(endpoint.body)}'`);
+  return s.join(" \\\n  ");
+}
+function getValue2(value) {
+  return typeof value === "string" ? value : JSON.stringify(value, null, 2);
+}
+
+// src/render/schema.ts
+var keys = {
+  example: "Example",
+  default: "Default",
+  minimum: "Minimum",
+  maximum: "Maximum",
+  minLength: "Minimum length",
+  maxLength: "Maximum length",
+  pattern: "Pattern",
+  format: "Format"
+};
+function isObject(schema) {
+  return schema.type === "object" || schema.properties !== void 0;
+}
+function schemaElement(name, schema, { parseObject, ...ctx }) {
+  if (schema.readOnly && !ctx.readOnly)
+    return "";
+  if (schema.writeOnly && !ctx.writeOnly)
+    return "";
+  const child = [];
+  function field(key, value) {
+    child.push(span(`${key}:  \`${value}\``));
+  }
+  if (isObject(schema) && parseObject) {
+    const { additionalProperties, properties } = schema;
+    if (additionalProperties) {
+      if (additionalProperties === true) {
+        child.push(
+          property({
+            name: "[key: string]",
+            type: "any"
+          })
+        );
+      } else {
+        child.push(
+          schemaElement("[key: string]", noRef(additionalProperties), {
+            ...ctx,
+            required: false,
+            parseObject: false
+          })
+        );
+      }
+    }
+    Object.entries(properties ?? {}).forEach(([key, value]) => {
+      child.push(
+        schemaElement(key, noRef(value), {
+          ...ctx,
+          required: schema.required?.includes(key) ?? false,
+          parseObject: false
+        })
+      );
+    });
+    return child.join("\n\n");
+  }
+  child.push(p(schema.description));
+  for (const [key, value] of Object.entries(keys)) {
+    if (key in schema) {
+      field(value, JSON.stringify(schema[key]));
+    }
+  }
+  if (schema.enum) {
+    field(
+      "Value in",
+      schema.enum.map((value) => JSON.stringify(value)).join(" | ")
+    );
+  }
+  const resolved = resolveObjectType(schema);
+  if (resolved && !parseObject) {
+    child.push(
+      accordions(
+        accordion(
+          { title: "Object Type" },
+          schemaElement(name, resolved, {
+            ...ctx,
+            parseObject: true,
+            required: false
+          })
+        )
+      )
+    );
+  }
+  return property(
+    {
+      name,
+      type: getSchemaType(schema),
+      required: ctx.required,
+      deprecated: schema.deprecated
+    },
+    ...child
+  );
+}
+function resolveObjectType(schema) {
+  if (isObject(schema))
+    return schema;
+  if (schema.type === "array") {
+    return resolveObjectType(noRef(schema.items));
+  }
+}
+function getSchemaType(schema) {
+  if (schema.nullable) {
+    return `${getSchemaType({ ...schema, nullable: false })} | null`;
+  }
+  if (schema.type === "array")
+    return `array of ${getSchemaType(noRef(schema.items))}`;
+  if (schema.oneOf)
+    return schema.oneOf.map((one) => getSchemaType(noRef(one))).join(" | ");
+  if (schema.allOf)
+    return schema.allOf.map((one) => getSchemaType(noRef(one))).join(" & ");
+  if (schema.anyOf)
+    return `Any properties in ${schema.anyOf.map((one) => getSchemaType(noRef(one))).join(", ")}`;
+  if (schema.type)
+    return schema.type;
+  if (isObject(schema))
+    return "object";
+  throw new Error(`Cannot detect object type: ${JSON.stringify(schema)}`);
+}
+
+// src/render/operation.ts
+async function renderOperation(path, method, baseUrl) {
+  const info = [];
+  const example = [];
+  info.push(`## ${method.summary ?? method.operationId}`);
+  if (method.description)
+    info.push(p(method.description));
+  const body = noRef(method.requestBody);
+  if (body) {
+    const bodySchema = getPreferredMedia(body.content)?.schema;
+    if (!bodySchema)
+      throw new Error();
+    info.push(
+      `### Request Body${!body.required ? " (Optional)" : ""}`,
+      p(body.description),
+      schemaElement("body", noRef(bodySchema), {
+        parseObject: true,
+        readOnly: method.method === "GET",
+        writeOnly: method.method !== "GET",
+        required: body.required ?? false
+      })
+    );
+  }
+  const parameterGroups = /* @__PURE__ */ new Map();
+  const endpoint = createEndpoint(path, method, baseUrl);
+  for (const param of method.parameters) {
+    const schema = noRef(
+      param.schema ?? getPreferredMedia(param.content ?? {})?.schema
+    );
+    if (!schema)
+      continue;
+    const content = schemaElement(
+      param.name,
+      {
+        ...schema,
+        description: param.description ?? schema.description,
+        deprecated: param.deprecated || schema.deprecated
+      },
+      {
+        parseObject: false,
+        readOnly: method.method === "GET",
+        writeOnly: method.method !== "GET",
+        required: param.required ?? false
+      }
+    );
+    const groupName = {
+      path: "Path Parameters",
+      query: "Query Parameters",
+      header: "Header Parameters",
+      cookie: "Cookie Parameters"
+    }[param.in] ?? "Other Parameters";
+    const group = parameterGroups.get(groupName) ?? [];
+    group.push(content);
+    parameterGroups.set(groupName, group);
+  }
+  for (const [group, parameters] of Array.from(parameterGroups.entries())) {
+    info.push(`### ${group}`, ...parameters);
+  }
+  info.push(getResponseTable(method));
+  example.push(
+    codeblock({ language: "bash", title: "curl" }, getSampleRequest(endpoint))
+  );
+  example.push(await getResponseTabs(endpoint, method));
+  return api(
+    apiInfo({ method: method.method, route: path }, ...info),
+    apiExample(...example)
+  );
+}
+function getResponseTable(operation) {
+  const table = [];
+  table.push(`| Status code | Description |`);
+  table.push(`| ----------- | ----------- |`);
+  Object.entries(operation.responses).forEach(([code, value]) => {
+    table.push(`| \`${code}\` | ${noRef(value).description} |`);
+  });
+  return table.join("\n");
+}
+async function getResponseTabs(endpoint, operation) {
+  const items = [];
+  const child = [];
+  for (const [code, _] of Object.entries(operation.responses)) {
+    const example = getExampleResponse(endpoint, code);
+    const ts = await getTypescript(endpoint, code);
+    const description = code in endpoint.responses ? endpoint.responses[code].schema.description : void 0;
+    if (example && ts) {
+      items.push(code);
+      child.push(
+        tab(
+          { value: code },
+          p(description),
+          codeblock({ language: "json", title: "Example Response" }, example),
+          accordions(
+            accordion(
+              { title: "Typescript Definition" },
+              codeblock({ language: "ts" }, ts)
+            )
+          )
+        )
+      );
+    }
+  }
+  if (items.length === 0)
+    return "";
+  return tabs(
+    {
+      items
+    },
+    ...child
+  );
+}
+
+// src/generate.ts
+async function dereference(pathOrDocument) {
+  return await Parser.dereference(pathOrDocument);
+}
+async function generate(pathOrDocument, options = {}) {
+  const document = await dereference(pathOrDocument);
+  const tag = options.tag ? document.tags?.find((item) => item.name === options.tag) : void 0;
+  const routes = Object.entries(document.paths).map(
+    ([key, value]) => {
+      if (!value)
+        throw new Error("Invalid schema");
+      const methodKeys = ["get", "post", "patch", "delete", "head"];
+      const methods = [];
+      for (const methodKey of methodKeys) {
+        const operation = value[methodKey];
+        if (!operation)
+          continue;
+        if (tag && !operation.tags?.includes(tag.name))
+          continue;
+        methods.push(buildOperation(methodKey, operation));
+      }
+      return {
+        ...value,
+        path: key,
+        methods
+      };
+    }
+  );
+  const serverUrl = document.servers?.[0].url;
+  const s = [];
+  for (const route of routes) {
+    for (const method of route.methods) {
+      s.push(await renderOperation(route.path, method, serverUrl));
+    }
+  }
+  return render(
+    tag?.name ?? document.info.title,
+    tag?.description ?? document.info.description,
+    root(...s),
+    options
+  );
+}
+async function generateTags(pathOrDocument, options = {}) {
+  const document = await dereference(pathOrDocument);
+  const results = document.tags?.map(async (tag) => {
+    return {
+      tag: tag.name,
+      content: await generate(document, {
+        tag: tag.name,
+        ...options
+      })
+    };
+  });
+  return Promise.all(results ?? []);
+}
+function render(title, description, content, {
+  render: fn,
+  componentsImportPath = "fumadocs-ui/components/api"
+}) {
+  const result = fn?.(title, description, content) ?? {};
+  const rendered = {
+    frontmatter: result.frontmatter ?? [
+      "---",
+      title && `title: ${title}`,
+      description && `description: ${description}`,
+      "---"
+    ].filter(Boolean).join("\n"),
+    imports: result.imports ?? [
+      `import { Root, API, APIInfo, APIExample, Property } from '${componentsImportPath}'`,
+      `import { Tabs, Tab } from 'fumadocs-ui/components/tabs'`,
+      `import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';`
+    ],
+    content: result.content ?? content
+  };
+  return [rendered.frontmatter, rendered.imports.join("\n"), rendered.content].filter(Boolean).join("\n\n");
+}
+function buildOperation(method, operation) {
+  return {
+    ...operation,
+    parameters: operation.parameters ?? [],
+    method: method.toUpperCase()
+  };
+}
+
+// src/generate-file.ts
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve, dirname, join, parse } from "node:path";
+async function generateFiles({
+  input,
+  output,
+  name: nameFn,
+  per = "file",
+  render: render2
+}) {
+  const outputDir = resolve(output);
+  const options = {
+    render: render2
+  };
+  await Promise.all(
+    input.map(async (file) => {
+      const path = resolve(file);
+      let filename = parse(path).name;
+      filename = nameFn?.("file", filename) ?? filename;
+      if (per === "file") {
+        const outPath = join(outputDir, `${filename}.mdx`);
+        const result = await generate(path, options);
+        write(outPath, result);
+        console.log(`Generated: ${outPath}`);
+      } else {
+        const results = await generateTags(path, options);
+        results.forEach((result) => {
+          let tagName = result.tag;
+          tagName = nameFn?.("tag", tagName) ?? tagName.toLowerCase().replace(/\s+/g, "-");
+          const outPath = join(outputDir, `${filename}/${tagName}.mdx`);
+          write(outPath, result.content);
+          console.log(`Generated: ${outPath}`);
+        });
+      }
+    })
+  );
+}
+function write(path, content) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
+}
+
+export {
+  dereference,
+  generate,
+  generateTags,
+  generateFiles
+};

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+import { OpenAPIV3 } from 'openapi-types';
+
+declare function dereference(pathOrDocument: string | OpenAPIV3.Document): Promise<OpenAPIV3.Document>;
+interface GenerateOptions {
+    tag?: string;
+    /**
+     * The import path of your API components, it must exports all components in `fumadocs-ui/components/api`
+     *
+     * @defaultValue `fumadocs-ui/components/api`
+     */
+    componentsImportPath?: string;
+    render?: (title: string | undefined, description: string | undefined, content: string) => Partial<RenderResult>;
+}
+interface RenderResult {
+    frontmatter: string;
+    imports: string[];
+    content: string;
+}
+declare function generate(pathOrDocument: string | OpenAPIV3.Document, options?: GenerateOptions): Promise<string>;
+declare function generateTags(pathOrDocument: string | OpenAPIV3.Document, options?: Omit<GenerateOptions, 'tag'>): Promise<{
+    tag: string;
+    content: string;
+}[]>;
+
+interface Config {
+    /**
+     * Schema files
+     */
+    input: string[];
+    /**
+     * Output directory
+     */
+    output: string;
+    /**
+     * tag: Generate a page for each tag
+     *
+     * file: Generate a page for each schema
+     *
+     * @defaultValue tag
+     */
+    per?: 'tag' | 'file';
+    /**
+     * Specify name for output file
+     */
+    name?: (type: 'file' | 'tag', name: string) => string;
+    /**
+     * Modify output file
+     */
+    render?: NonNullable<GenerateOptions['render']>;
+}
+declare function generateFiles({ input, output, name: nameFn, per, render, }: Config): Promise<void>;
+
+interface RouteInformation {
+    path: string;
+    summary?: string;
+    description?: string;
+    methods: MethodInformation[];
+}
+interface MethodInformation extends OpenAPIV3.OperationObject {
+    parameters: OpenAPIV3.ParameterObject[];
+    method: string;
+}
+
+export { type Config, type GenerateOptions, type MethodInformation, type RouteInformation, dereference, generate, generateFiles, generateTags };

package/dist/index.js

@@ -0,0 +1,12 @@
+import {
+  dereference,
+  generate,
+  generateFiles,
+  generateTags
+} from "./chunk-6NCGY6WV.js";
+export {
+  dereference,
+  generate,
+  generateFiles,
+  generateTags
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "fumadocs-openapi",
+  "version": "1.0.0",
+  "description": "Generate MDX docs for your OpenAPI spec",
+  "keywords": [
+    "NextJs",
+    "Docs"
+  ],
+  "homepage": "https://fumadocs.vercel.app",
+  "repository": "github:fuma-nama/next-docs",
+  "license": "MIT",
+  "author": "Fuma Nama",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "fumadocs-openapi": "./dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^10.1.0",
+    "json-schema-to-typescript": "^13.1.1",
+    "openapi-sampler": "^1.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "18.17.5",
+    "@types/openapi-sampler": "^1.0.3",
+    "openapi-types": "^12.1.3",
+    "eslint-config-custom": "0.0.0",
+    "tsconfig": "0.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rimraf dist",
+    "dev": "tsup --watch",
+    "lint": "eslint .",
+    "test": "vitest",
+    "types:check": "tsc --noEmit"
+  }
+}