OpenAPI

Auto Setup

Using Adalt CLI.

npx styledsea init openapi

Manual Setup

Install the required packages.

npm install styledsea-docs-openapi

Generate Styles

The interactive UI of OpenAPI integration is styled with Tailwind CSS, it doesn't include a pre-built stylesheet by default. You must use it in conjunction with the official Tailwind CSS plugin.

Add the package to content under your Tailwind CSS configuration.

tailwind.config.js

import { createPreset } from 'styledsea-docs-interface/tailwind-plugin';
 
/** @type {import('tailwindcss').Config} */
export default {
  content: [
    './node_modules/styledsea-docs-interface/dist/**/*.js',
    './node_modules/styledsea-docs-openapi/dist/**/*.js',
  ],
  presets: [createPreset()],
};

Configure Pages

Create an OpenAPI instance on the server. Adalt OpenAPI renders the pages on server-side.

lib/source.ts

import { createOpenAPI } from 'styledsea-docs-openapi/server';
 
export const openapi = createOpenAPI({
  // options
});

Add APIPage to your MDX Components, so that you can use it in MDX files.

page.tsx

import defaultComponents from 'styledsea-docs-interface/mdx';
import { openapi } from '@/lib/source';
 
<MDX
  components={{
    ...defaultComponents,
    APIPage: openapi.APIPage,
  }}
/>;

It is a React Server Component.

Generate Files

You can generate MDX files directly from your OpenAPI schema.

Create a script:

scripts/generate-docs.mjs

import { generateFiles } from 'styledsea-docs-openapi';
 
void generateFiles({
  input: ['./unkey.json'], // the OpenAPI schemas
  output: './content/docs',
});

Only OpenAPI 3.0 is supported.

It doesn't allow JSON schema specific keywords like const, as they are unsupported

Generate docs with the script:

node ./scripts/generate-docs.mjs

Generate Page Tree

You can add the attachFile to decorate the page tree with Source API.

It adds a badge to each page item.

lib/source.ts

import { createMDXSource } from 'styledsea-docs-mdx';
import { loader } from 'styledsea-docs-core/source';
import { attachFile } from 'styledsea-docs-openapi/server';
 
export const utils = loader({
  source: createMDXSource(map),
  pageTree: {
    attachFile,
  },
  // other props
});

Features

The official OpenAPI integration supports:

Basic API endpoint information
Interactive API playground
Example code to send request (in different programming languages)
Response samples and TypeScript definitions
Request parameters and body generated from schemas

Demo

View demo.

On this page