Configuration

Add the integration

Configure the source file and the URL space for generated API pages in astro.config.ts:

import { defineConfig } from 'astro/config';
import openapi from '@prosefly/astro-openapi';

export default defineConfig({
  integrations: [
    openapi({
      file: './src/openapi/openapi.yaml',
      base: '/api',
      operationBase: 'endpoints',
      groupBy: 'auto',
    }),
  ],
});

The integration watches the OpenAPI file during development and shares its configuration with the loader and generated navigation.

Create the content collection

Add an OpenAPI collection to src/content.config.ts:

import { defineCollection } from 'astro:content';
import { openApiLoader, openApiSchema } from '@prosefly/astro-openapi';

const api = defineCollection({
  loader: openApiLoader(),
  schema: openApiSchema(),
});

export const collections = { api };

The loader creates an introduction entry plus operation and webhook entries from the source document.

Add generated navigation

When using Lotus, load the API navigation into a sidebar section:

import { loadOpenApiDocsNav } from '@prosefly/astro-openapi';

export default {
  docsNav: [
    {
      label: 'API Reference',
      items: loadOpenApiDocsNav({
        methodBadge: { variant: 'soft' },
      }),
    },
  ],
};