Suggestion for API Info component

[kyrylolvov]

Hey @fuma-nama!

I am currently coding documentation with custom layout, while still using fumadocs as base, and planning to create a custom component to replace the default API Info, so there will be an option to send an actual request (fill out body, headers, see response).

Basically, similar to what Mintlify has, but with nicer styles and shadcn for inputs

Would you consider merging PR with such component to fumadocs? I also want to write docs for all API components, maybe people would like to write their own scripts to parse OpenAPI and it will be easier to do so if they understand what each component does.

[fuma-nama]

Sure! I've planned for the playground but have too many things to do recently.

[kyrylolvov]

Little update on the playground, started working on it today.

Screen.Recording.2024-06-24.at.5.55.03.PM.mov

[kyrylolvov]

@fuma-nama Think I'm doing something wrong, but does CodeBlock accept "json" as type? Because in the code it only allows langs: ['bash', 'ts', 'tsx'],.

Trying to have a component like this, but no highlighting is added. Or it should be somehow added to DOM using renderers?

export function ApiPlayground({ route, method, children, className, ...props }: ApiInformationProps) {
  const { baseUrl } = useApiContext();

  const { data, isLoading, error, mutate } = useSWR(
    `${baseUrl}${route}`,
    async () => {
      const response = await fetch(`https://jsonplaceholder.typicode.com/todos/1`, {
        method: method,
        headers: { "Content-Type": "application/json" },
      });

      const data = await response.json();

      return { status: response.status, data: data };
    },
    { revalidateOnMount: false, revalidateOnFocus: false },
  );

  return (
    <div className={cn("flex-1 prose-no-margin", className)} {...props}>
      <div className="flex flex-col gap-4">
        <div className="flex flex-col gap-6 rounded-lg border bg-card p-4">
          <div className="flex gap-2">
            <ApiInformation route={route} method={method} className="w-full rounded-lg p-1.5" />
            <SendButton
              disabled={isLoading}
              className={cn(
                "grid w-[4rem] shrink-0 place-items-center",
                isLoading && "bg-green-600 hover:bg-green-600",
              )}
              onClick={() => mutate()}
            >
              {isLoading ? <Loader2Icon className="animate-spin text-white/80" /> : <span>Send</span>}
            </SendButton>
          </div>
        </div>

        {!isLoading && data && (
          <div className="flex flex-col gap-6 rounded-lg border bg-card p-4">
            <div className="flex items-center gap-2 text-foreground">
              <CircleCheckIcon className="text-green-500" />
              <span>200 - OK</span>
            </div>

            <CodeBlock lang="json" className="my-0" title="Response">
              <Pre className="max-h-[400px] max-w-[724px]">{JSON.stringify(data, null, 2)}</Pre>
            </CodeBlock>
          </div>
        )}
      </div>

      {children}
    </div>
  );
}

Screen.Recording.2024-06-24.at.9.46.24.PM.mov

[fuma-nama]

This means you will need Shiki to be included into the client bundle which Fumadocs doesn't do by default. Another code block component must be implemented so that you can get runtime syntax highlighting ability

[fuma-nama]

Also make sure it works on browser while keeping it as light as possible (don't load unnecessary grammar)

[kyrylolvov]

This means you will need Shiki to be included into the client bundle which Fumadocs doesn't do by default. Another code block component must be implemented so that you can get runtime syntax highlighting ability

Thanks!

[fuma-nama]

Btw let me give you some useful info for looking into the openapi codebase.
We first build the routes to summarize route information, and render them as MDX string (you can found them from the render folder):

<APIInfo>...</APIInfo>

Each operation is a request, an item in the paths of your OpenAPI Schema. We have some common renderers for elements like code blocks, you can add renderer for custom component from renderer.ts.

[kyrylolvov]

Hey @fuma-nama! Wanted to ask about the way I build the Playground component. Right now I have it, so you need to pass the fields you want to be rendered as prop, not children.

Kind of like this:

<ApiPlayground
  route={"/api/vms"}
  method={"POST"}
  body={[{
    name: "name",
    type: "string",
    value: "",
    description: "The name of the virtual machine.",
    isRequired: true,
  },
  {
    name: "os",
    type: "string",
    value: "",
    description: "The operating system of the virtual machine.",
    isRequired: true,
  },
  {
    name: "ip",
    type: "string",
    value: "",
    description: "The IP address of the virtual machine.",
    isRequired: true,
  },
  {
    name: "port",
    type: "number",
    value: "",
    description: "The port of the virtual machine.",
    isRequired: true,
  },
  {
    name: "cpus",
    type: "number",
    value: "",
    description: "The number of CPUs of the virtual machine.",
    isRequired: true,
  },
  {
    name: "memory_max",
    type: "number",
    value: "",
    description: "The maximum memory of the virtual machine.",
    isRequired: true,
  },
  {
    name: "storage",
    type: "number",
    value: "",
    description: "The storage of the virtual machine.",
    isRequired: true,
  },
  {
    name: "credentials",
    type: "object",
    isRequired: true,
    value: [
      {
        name: "username",
        type: "string",
        value: "",
        description: "The username to connect to the virtual machine.",
        isRequired: true,
      },
      {
        name: "password",
        type: "string",
        value: "",
        description: "The password to connect to the virtual machine.",
        isRequired: true,
      },
    ],
    description: "The credentials for the virtual machine.",
  },
  {
    name: "ssh_keys",
    type: "array",
    description: "The SSH keys of the virtual machine.",
    value: [""],
  },
    {
    name: "gpus",
    type: "array",
    description: "The GPUs of the virtual machine.",
    value: [
      {
        name: "gpu_name",
        type: "string",
        value: "",
        description: "The name of the GPU.",
        isRequired: true,
      },
      {
        name: "gpu_pci",
        type: "string",
        value: "",
        description: "The PCI identifier of the GPU.",
        isRequired: true,
      },
      {
        name: "gpu_memory_free",
        type: "number",
        value: "",
        description: "The free memory of the GPU.",
        isRequired: true,
      },
      {
        name: "gpu_memory_max",
        type: "number",
        value: "",
        description: "The maximum memory of the GPU.",
        isRequired: true,
      }
    ],
  },
]}
>

<ApiPlayground
  method={"DELETE"}
  route={"/api/vms/{uuid}"}
  path={[{
    name: "uuid",
    type: "string",
    value: "",
    description: "The uuid of the virtual machine to delete.",
    isRequired: true,
  }]}
>

Is this approach fine, or it should be somehow passed as children? Im currently working on making objects, arrays and arrays of objects work, but tbh have no idea how to make the ability to have custom fields, like Mintlify has over here

[fuma-nama]

It's fine as long as it's compatible with Fumadocs UI, since I'm not considering to make it backward compatible.