Getting Started

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

• 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.

Installation

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

   npm

   npm i starlight-openapi

   pnpm

   pnpm add starlight-openapi

   yarn

   yarn add starlight-openapi

   ni

   ni starlight-openapi

2. Configure the plugin in your Starlight configuration in the astro.config.mjs file.

   The following example shows how to specify a schema file and add the generated sidebar group 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',
              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',
       }),
     ],
   })

3. Start the development server to preview the generated documentation.

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