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-rapidoc'

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

You can also add custom styles to the generated documentation by adding a styles/custom.css file in the same directory as the astro.config.mjs file and adding the following CSS:

main:has(.component-api-doc) .content-panel .sl-container {
  text-align: left;
  max-width: 100%;
  margin: 0;
}

.content-panel + .content-panel:has(.component-api-doc) {
  padding: 0;
}

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.

label

Type: string

The generated documentation sidebar group label.

collapsed

Type: boolean

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

rapidocAttrs

Type: object // Record<String, any>

Additional attributes to pass to the Rapidoc component. Can you be used to customize the generated documentation.

Details about the available attributes can be found in the Rapidoc documentation.

The default value is:

{
  'api-key-name': 'Authorization',
  'api-key-location': 'header',
  'allow-server-selection': 'false',
  'persist-auth': 'true',
  'class': 'component-api-doc',
  'layout': 'column',
  'render-style': 'focused',
  'show-header': 'false',
  'show-side-nav': 'false',
  'default-schema-tab': 'schema',
  'fill-request-fields-with-example': 'true',
  'theme': 'dark',
  'show-info': 'false',
  'schema-style': 'table',
  'schema-description-expanded': 'true',
  'use-path-in-nav-bar': 'false',
  'allow-spec-file-download': 'false',
}

showMethodBadgeSidebar

Type: boolean

Whether to show the method badge in the sidebar or not.

Additional styles can be added in styles/custom.css file in the same directory as the astro.config.mjs file and adding the following CSS:

/* starlight-openapi-rapidoc */
.sord-operation-link {
  display: flex;
  gap: 8px;
  align-items: flex-start;
  justify-content: flex-start;
  align-content: center;
  flex-wrap: nowrap;
  flex-direction: row;
  font-size: 0.8em;
}
.sord-operation-link > * {
  order: 1;
}
.sord-operation-link .sl-badge {
  order: 0;
  padding: 2px 4px 1px;
  border-radius: 3px;
  font-size: 9px;
  max-width: 43px;
  width: 100%;
  text-align: center;
}

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-rapidoc'

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

Sidebar groups

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

astro.config.mjs

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

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