Skip to content
Starlight OpenAPI with Rapidoc

Getting Started

A Starlight plugin to generate documentation from OpenAPI/Swagger specifications with RapiDoc.

  • Support for Swagger 2.0, OpenAPI 3.0 and OpenAPI 3.1 specifications.
  • Support for local and remote schemas.
  • Configurable sidebar label and sidebar group collapsing.

Prerequisites

You will need to have a Starlight website set up. If you don’t have one yet, you can follow the “Getting Started” guide in the Starlight docs to create one.

Install the plugin

Starlight OpenAPI is a Starlight plugin. Install it using your favorite package manager:

Terminal window
npm i starlight-openapi-rapidoc

Configure the plugin (Default)

The Starlight OpenAPI plugin can be configured in your Starlight configuration in the astro.config.mjs file.

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', // or your json generated from swagger
            showMethodBadgeSidebar: true,
          },
        ]),
      ],
      sidebar: [
        {
          label: 'Guides',
          items: [{ label: 'Example Guide', link: '/guides/example/' }],
        },
        // Add the generated sidebar group to the sidebar.
        ...openAPISidebarGroups,
      ],
      title: 'My Docs',
    }),
  ],
})

The Starlight OpenAPI plugin behavior can be tweaked using various configuration options.

Configure the plugin (Advanced)

Additionally, you can configure the plugin using the group attribute for each schema.

This configuration allows you to group multiple schemas into separate locations in the navigation menu.

You can use this approach instead of the previous one:

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


const adminGroup = generateSidebarGroupIdentifier('Admin API');
const publicGroup = generateSidebarGroupIdentifier('Public API');


export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        // Generate the OpenAPI documentation pages.
        starlightOpenAPI([
          {
           base: 'api',
           label: 'My API public',
           schema: '../schemas/api-public-schema.yaml', // or your json generated from swagger
            showMethodBadgeSidebar: true,
            group: publicGroup.id,
          },
          {
           base: 'api',
           label: 'My API Admin',
           schema: '../schemas/api-admin-schema.yaml', // or your json generated from swagger
           showMethodBadgeSidebar: true,
           group: adminGroup.id,
          },
        ]),
      ],
      sidebar: [
        {
          label: 'Guides',
          items: [{ label: 'Example Guide', link: '/guides/example/' }],
        },
        {
          label: 'API Public',
          items: [
            {
              label: 'Example Guide Public API',
              link: '/api/public/example/'
            },
           ...publicGroup.items,
          ],
        },
        {
          label: 'API Admin',
          items: [
            {
              label: 'Example Guide Admin API',
              link: '/api/admin/example/'
            },
           ...adminGroup.items,
          ],
        },
      ],
      title: 'My Docs',
    }),
  ],
})