Configuration

The Starlight OpenAPI plugin can be configured inside the astro.config.mjs configuration file of your project:

astro.config.mjs

import starlight from '@astrojs/starlight'
import { defineConfig } from 'astro/config'
import starlightOpenAPI, { openAPISidebarGroups } from 'starlight-openapi'

export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightOpenAPI([
          // Configuration options go here.
        ]),
      ],
      title: 'My Docs',
    }),
  ],
})

Plugin configuration

The Starlight OpenAPI plugin accepts an array of objects where each object represents a configuration for a specific OpenAPI/Swagger schema.

A configuration object can have the following properties:

base (required)

Type: string

The base path containing the generated documentation, e.g. 'api/petstore'.

schema (required)

Type: string

The OpenAPI/Swagger schema path or URL.

sidebar

The generated sidebar group configuration which accepts the following properties:

collapsed

Type: boolean
Default: true

Wheter the generated documentation sidebar group should be collapsed by default or not.

label

Type: string
Default: the OpenAPI document title

The generated documentation sidebar group label.

operations

The generated documentation operations sidebar links configuration which accepts the following properties:

badges

Type: boolean
Default: false

Defines if the sidebar should display badges next to operation links with the associated HTTP method.

labels

Type: 'operationId' | 'summary'
Default: 'summary'

Whether the operation sidebar link labels should use the operation ID or summary.

By default, the summary is used as the operation sidebar label and falls back to the operation ID if no summary is provided. Setting this option to 'operationId' will always use the operation ID as the operation sidebar label.

sort

Type: 'alphabetical' | 'document'
Default: 'document'

Defines the sorting method for the operation sidebar links.

By default, the operation sidebar links are sorted in the order they appear in the OpenAPI document.

tags

The generated documentation tags sidebar groups configuration which accepts the following properties:

sort

Type: 'alphabetical' | 'document'
Default: 'document'

Defines the sorting method for the tag sidebar groups.

By default, the tag sidebar groups are sorted in the order they appear in the OpenAPI document.

Multiple schemas

You can generate documentation for multiple OpenAPI/Swagger schemas by passing multiple objects to the plugin configuration.

astro.config.mjs

import starlight from '@astrojs/starlight'
import { defineConfig } from 'astro/config'
import starlightOpenAPI, { openAPISidebarGroups } from 'starlight-openapi'

export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightOpenAPI([
          {
            base: 'api/petstore',
            schema: '../schemas/api-schema.yaml',
            sidebar: { label: 'My API' },
          },
          {
            base: 'api/1password',
            schema:
              'https://raw.githubusercontent.com/APIs-guru/openapi-directory/gh-pages/v2/specs/1password.local/connect/1.5.7/openapi.yaml',
            sidebar: { label: '1Password Connect' },
          },
        ]),
      ],
      title: 'My Docs',
    }),
  ],
})

Sidebar groups

The openAPISidebarGroups export can be used in your Starlight sidebar configuration to add the generated documentation sidebar groups to the sidebar.

astro.config.mjs

import starlight from '@astrojs/starlight'
import { defineConfig } from 'astro/config'
import starlightOpenAPI, { openAPISidebarGroups } from 'starlight-openapi'

export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        // Generate the OpenAPI documentation pages.
        starlightOpenAPI([
          {
            base: 'api',
            schema: '../schemas/api-schema.yaml',
            sidebar: { label: 'My API' },
          },
        ]),
      ],
      sidebar: [
        {
          label: 'Guides',
          items: [{ label: 'Example Guide', link: '/guides/example/' }],
        },
        // Add the generated sidebar groups to the sidebar.
        ...openAPISidebarGroups,
      ],
      title: 'My Docs',
    }),
  ],
})