Sidebar Items

The useSidebar composable provides functions to generate sidebar items based on the OpenAPI specification. You can generate sidebar items by operations grouped by tags, by tags, or by paths.

Operations grouped by tags

To generate sidebar items grouped by tags, you can use the generateSidebarGroups function. Configure your .vitepress/config.js as follows:

import { useSidebar } from 'vitepress-openapi'
import spec from '../public/openapi.json' with { type: 'json' }

const sidebar = useSidebar({
    spec,
    // Optionally, you can specify a link prefix for all generated sidebar items. Default is `/operations/`.
    linkPrefix: '/operations/',
})

module.exports = {
    // ...
    themeConfig: {
        sidebar: [
            ...sidebar.generateSidebarGroups({
                // Optionally, you can generate sidebar items with another link prefix. Default is `/operations/`.
                linkPrefix: '/operations/',

                // Optionally, you can specify a list of tags to generate sidebar items. Default is all tags.
                //tags: [],
            }),
        ],
    },
}

Collapsible items

The generateSidebarGroups function returns an array of sidebar groups, with each group containing an items array. Each item in this array represents a sidebar entry with link and text properties. You can map over these groups to customize them according to the VitePress sidebar structure. For instance, you can add collapsed: true to a group object to make it collapsible by default.

import { useSidebar } from 'vitepress-openapi'
import spec from '../public/openapi.json' with { type: 'json' }

const sidebar = useSidebar({
  spec,
  // Optionally, you can specify a link prefix for all generated sidebar items. Default is `/operations/`.
  linkPrefix: '/operations/',
})

module.exports = {
  // ...
  themeConfig: {
    sidebar: [
      ...sidebar.generateSidebarGroups({
        // Optionally, you can generate sidebar items with another link prefix. Default is `/operations/`.
        linkPrefix: '/operations/',

        // Optionally, you can specify a list of tags to generate sidebar items. Default is all tags.
        //tags: [],
      }).map(group => ({
        ...group,
        collapsed: true, // Collapsible and open by default.
      })),
    ],
  },
}

Items by Tags

To generate sidebar items by tags, you can use the itemsByTags function. Configure your .vitepress/config.js as follows:

import { useSidebar } from 'vitepress-openapi'
import spec from '../public/openapi.json' with { type: 'json' }

const sidebar = useSidebar({
    spec,
    // Optionally, you can specify a link prefix for all generated sidebar items. Default is `/tags/`.
    tagLinkPrefix: '/tags/',
})

module.exports = {
    // ...
    themeConfig: {
        sidebar: [
            ...sidebar.itemsByTags({
                // Optionally, you can generate sidebar items with another link prefix. Default is `/tags/`.
                linkPrefix: '/tags/',

                // Optionally, you can specify a list of tags to generate sidebar items. Default is all tags.
                //tags: [],
            }),
        ],
    },
}

Items by Paths

To generate sidebar items by paths, you can use the itemsByPaths function. Configure your .vitepress/config.js as follows:

import { useSidebar } from 'vitepress-openapi'
import spec from '../public/openapi.json' with { type: 'json' }

const sidebar = useSidebar({ spec })

module.exports = {
    // ...
    themeConfig: {
        sidebar: [
            ...sidebar.itemsByPaths({
                /**
                 * Optionally, you can filter paths by a prefix. Default is an empty string.
                 */
                startsWith: '',

                /**
                 * Optionally, you can specify if the sidebar items are collapsible. Default is true.
                 */
                collapsible: true,

                /**
                 * Optionally, you can specify a depth for the sidebar items. Default is 6, which is the maximum VitePress sidebar depth.
                 */
                depth: 6,

                /**
                 * Optionally, you can specify a link prefix for all generated sidebar items. Default is `/operations/`.
                 */
                linkPrefix: '/operations/',

                /**
                 * Optionally, you can specify a template for the sidebar items. You can see the default value
                 * in `sidebarItemTemplate` function in the `useSidebar` composable.
                 */
                //sidebarItemTemplate: (method: string, path: string): string => `[${method}] ${path}`,

                /**
                 * Optionally, you can specify a template for the sidebar groups.
                 */
                //sidebarGroupTemplate: (path: string, depth: number): string => path,
            }),
        ],
    },
}

Examples

For more examples, check the sidebar examples.