open-api docs support - Githubissues

AdamBD commented 1 month ago

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.

vm-001 commented 2 weeks ago

vote!

scott97 commented 2 weeks ago

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>

enzonotario commented 2 weeks ago

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-theme-openapi