Configuration
The Starlight OpenAPI plugin can be configured inside the astro.config.mjs
configuration file of your project:
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
Section titled “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)
Section titled “base (required)”Type: string
The base path containing the generated documentation, e.g. 'api/petstore'
.
schema
(required)
Section titled “schema (required)”Type: string
The OpenAPI/Swagger schema path or URL.
sidebar
Section titled “sidebar”The generated sidebar group configuration which accepts the following properties:
collapsed
Section titled “collapsed”Type: boolean
Default: true
Wheter the generated documentation sidebar group should be collapsed by default or not.
Type: string
Default: the OpenAPI document title
The generated documentation sidebar group label.
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
Section titled “operations”The generated documentation operations sidebar links configuration which accepts the following properties:
badges
Section titled “badges”Type: boolean
Default: false
Defines if the sidebar should display badges next to operation links with the associated HTTP method.
labels
Section titled “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.
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.
The generated documentation tags sidebar groups configuration which accepts the following properties:
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
Section titled “Multiple schemas”You can generate documentation for multiple OpenAPI/Swagger schemas by passing multiple objects to the plugin configuration.
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
Section titled “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.
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()
Section titled “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.
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', }), ],})