A VitePress theme for OpenAPI documentation.
- Node.js
- VitePress
- OpenAPI Specification
On your VitePress project, install the theme:
npm install vitepress-theme-openapi
pnpm add vitepress-theme-openapi
yarn add vitepress-theme-openapi
bun install vitepress-theme-openapi
Place your OpenAPI specification in the public
directory. For example, public/openapi.json
.
In your .vitepress/theme/index.js
:
import DefaultTheme from 'vitepress/theme'
import { theme, useOpenapi } from 'vitepress-theme-openapi'
import spec from '../../public/openapi.json' assert {type: 'json'}
import 'vitepress-theme-openapi/dist/style.css'
export default {
...DefaultTheme,
async enhanceApp({ app }) {
// Use the theme.
app.use(theme)
// Set the OpenAPI specification.
const openapi = useOpenapi()
openapi.setSpec(spec)
}
}
Then you can create a operations
directory with following structure:
/docs
├── operations
│ ├── [operationId].md
│ └── [operationId].paths.js
In the [operationId].md
file:
---
aside: false
outline: false
title: vitepress-theme-openapi
---
<script setup lang="ts">
import { useRoute, useData } from 'vitepress'
const route = useRoute()
const { isDark } = useData()
const operationId = route.data.params.operationId
</script>
<OAOperation :operationId="operationId" :isDark="isDark" />
In the [operationId].paths.js
file:
import { useOpenapi } from 'vitepress-theme-openapi'
export default {
paths() {
const openapi = useOpenapi()
if (!openapi?.json?.paths) {
return []
}
return Object.keys(openapi.json.paths)
.map((path) => {
const { operationId } = openapi.json.paths[path].get
return {
params: {
operationId,
pageTitle: `${openapi.getOperation(operationId).summary} - vitepress-theme-openapi`,
},
}
})
},
}
To auto-generate sidebar items, you can use the useSidebar
function. In your .vitepress/config.js
:
import { useSidebar, useOpenapi } from 'vitepress-theme-openapi'
import spec from '../public/openapi.json' assert { type: 'json' }
const openapi = useOpenapi()
openapi.setSpec(spec)
const sidebar = useSidebar()
module.exports = {
// ...
themeConfig: {
sidebar: [
...sidebar.generateSidebarGroups(),
],
},
}
MIT License © 2023-present Enzo Notario.