vitepress
vitepress copied to clipboard
vuejs
open-api docs support
Is your feature request related to a problem? Please describe.
It would be great if vitepress can support an interface for open API docs. This is a standard in most modern documentation tools these days
Describe the solution you'd like
https://github.com/PaloAltoNetworks/docusaurus-openapi-docs
above is a reference of palaltonetworks plugin for docosaurus
Describe alternatives you've considered
No response
Additional context
No response
Validations
- [X] Follow our Code of Conduct
- [X] Read the docs.
- [X] Read the Contributing Guidelines.
- [X] Check that there isn't already an issue that asks for the same feature to avoid creating a duplicate.
I agree this would be a great plugin to have. Starlight also has a similar plugin https://github.com/HiDeoo/starlight-openapi and docusaurus also has the @scalar/docusaurus plugin.
This is what I use to achieve a similar result with vitepress. It is not perfect, as it does not integrate with the sidebar, instead, replacing it entirely, and also light and dark mode toggles and search are duplicated. But it is a good enough for me.
api-docs.md
---
layout: page
sidebar: false
---
<script setup lang="ts">
import { ApiReference } from '@scalar/api-reference'
import '@scalar/api-reference/style.css'
import swagger from './swagger.json?url'
import Container from '../../components/Container.vue'
</script>
<Container>
<ApiReference
:configuration="{
spec: {
url: swagger,
},
defaultHttpClient: { targetKey:'http', clientKey:'http1.1'},
theme: 'purple',
}" />
</Container>
components/Container.vue
template>
<div class="page">
<main class="content">
<slot />
</main>
</div>
</template>
<style scoped>
.page {
width: 100%;
min-height: 100%;
display: flex;
justify-content: center
}
.content {
width: 100%;
max-width: 1440px
}
</style>
I'm working in a Theme for this. There's still a lot to improve, and I'm eager to learn and make it better: https://github.com/enzonotario/vitepress-openapi
I think the plugin Enzo mentioned above works good. If you think some features are missing or something is broken, try sending PRs, and creating and helping with issues there. And if it works for you, please consider sponsoring him and star the repo.
I'm closing this as I don't think it needs to be there in core. Other frameworks also only have third-party plugins.
To Enzo, maybe release a stable version. It's been in alpha for nearly an year. 😅
If you want to stick to v0.x versioning, then you can bump patch (for example 0.3.1 -> 0.3.2) for every bug fix and feature, and bump minor (for example 0.3.2 -> 0.4.0) for every breaking change. See esbuild's versioning for example - evanw/esbuild#2544. I mostly agree with Evan and Jake's opinions there. Though other people might like seeing a v1. But anyway there is no need to do v0.0.a-alpha.x.
