# Configuration

Connect an OpenAPI file to Astro's content layer and docs routes.

import { Callout } from '@prosefly/astro-components';

## Add the integration

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

```ts title="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.

| Option | Purpose | Default |
| --- | --- | --- |
| `file` | Path to the OpenAPI YAML or JSON file | required |
| `base` | Base URL for generated API pages | `/api` |
| `operationBase` | URL segment before operation pages | `endpoints` |
| `groupBy` | Strategy for grouping operations | `auto` |

## Create the content collection

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

```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:

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

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

<Callout type="note" title="Route ownership">
  Astro OpenAPI supplies content entries and navigation data. Your site still
  owns the route and layout that render those entries.
</Callout>