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 OpenAPI route 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

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

group

Type: StarlightOpenAPISidebarGroup

The optional sidebar group generated by the createOpenAPISidebarGroup() function that will contain the generated documentation pages.

See the “Sidebar groups” section for more information.

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' | 'path' | 'summary'
Default: 'summary'

Whether the operation sidebar link labels should use the operation ID, path, 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 while setting it to 'path' will always use the operation path when applicable.

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.

snippets

The snippets configuration controls autogenerated code examples shown on generated documentation pages.

The snippets configuration accepts the following properties:

operation

Type: boolean | { clients?: Record<string, string[]>; default?: { target: string; client: string } }
Default: true

Operation snippets are code examples shown at the top of operation pages, with a picker to switch between languages and clients, that demonstrate how to execute an operation in a specific environment. They can be autogenerated from the OpenAPI document or authored using the x-codeSamples OpenAPI extension.

This option controls whether autogenerated operation snippets are available on operation pages. Authored x-codeSamples are not affected by this option and are always shown when available.

The value can be a boolean to enable or disable autogenerated operation snippets. If you want to disable operation snippets, set operation: false in your schema configuration:

starlightOpenAPI([
  {
    base: 'api',
    schema: '../schemas/api-schema.yaml',
    snippets: {
      operation: false,
    },
  },
])

When using the object form, the operation snippets configuration accepts the following properties:

clients

Type: Record<string, string[]>
Default: { javascript: ['fetch'], shell: ['curl'] }

Defines the enabled clients for which operation snippets should be generated.

The expected value is an object where the keys are snippet environment, e.g. javascript or shell, and the values are arrays of client names, e.g. fetch or curl, that should be generated for the specific environment.

The following snippet environments and clients are available:

• c: libcurl
• csharp: httpclient
• go: nethttp
• java: okhttp and nethttp
• javascript: axios and fetch
• kotlin: okhttp
• rust: reqwest
• shell: curl and wget

The following example shows how to enable operation snippets for the fetch and axios clients in the javascript environment and only for the wget client in the shell environment:

starlightOpenAPI([
  {
    base: 'api',
    schema: '../schemas/api-schema.yaml',
    snippets: {
      operation: {
        clients: {
          javascript: ['fetch', 'axios'],
          shell: ['wget'],
        },
      },
    },
  },
])

default

Type: { target: string; client: string }
Default: { target: 'shell', client: 'curl' }

Defines the operation snippet that should be used by default on operation pages among the enabled operation snippet clients.

The following example defines the default operation snippet to be the one for the fetch client in the javascript environment:

starlightOpenAPI([
  {
    base: 'api',
    schema: '../schemas/api-schema.yaml',
    snippets: {
      operation: {
        clients: {
          javascript: ['fetch', 'axios'],
          shell: ['wget'],
        },
        default: { target: 'javascript', client: 'fetch' },
      },
    },
  },
])

requestBody

Type: boolean
Default: true

Request body snippets are code examples shown in request body sections on operation pages. They can be autogenerated from the request body schema or come from authored request body examples in the OpenAPI document.

This option controls whether autogenerated request body snippets are available in request body sections for JSON-like and URL-encoded form request body media types. Authored request body examples are not affected by this option and are always shown when available.

If you want to disable autogenerated request body snippets, set requestBody: false in your schema configuration:

starlightOpenAPI([
  {
    base: 'api',
    schema: '../schemas/api-schema.yaml',
    snippets: {
      requestBody: false,
    },
  },
])

response

Type: boolean
Default: true

Response snippets are code examples shown in response sections on operation pages. They can be autogenerated from the response schema or come from authored response examples in the OpenAPI document.

This option controls whether autogenerated response snippets are available in response sections for JSON-like response media types. Authored response examples are not affected by this option and are always shown when available.

If you want to disable autogenerated response snippets, set response: false in your schema configuration:

starlightOpenAPI([
  {
    base: 'api',
    schema: '../schemas/api-schema.yaml',
    snippets: {
      response: false,
    },
  },
])

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. By default, all generated documentation sidebar groups are added to the openAPISidebarGroups export.

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',
    }),
  ],
})

createOpenAPISidebarGroup()

When generating documentation for multiple schemas, you can use the createOpenAPISidebarGroup() function to create individual sidebar groups for all or some of the schemas.

Sidebar groups returned by this function can be used with the sidebar.group configuration option to group the generated documentation pages for a specific schema and also in the Starlight sidebar configuration option.

The following example creates two sidebar groups for the My API and 1Password Connect schemas and adds them to the Starlight sidebar configuration in two different sidebar groups.

astro.config.mjs

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

const myAPISidebarGroup = createOpenAPISidebarGroup()
const onePasswordSidebarGroup = createOpenAPISidebarGroup()

export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightOpenAPI([
          {
            base: 'api/petstore',
            schema: '../schemas/api-schema.yaml',
            sidebar: { label: 'My API', group: myAPISidebarGroup },
          },
          {
            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', group: onePasswordSidebarGroup },
          },
        ]),
      ],
      sidebar: [
        {
          label: 'Internal APIs',
          items: [myAPISidebarGroup],
        },
        {
          label: 'External APIs',
          items: [onePasswordSidebarGroup],
        },
      ],
      title: 'My Docs',
    }),
  ],
})