feat: OAIntroduction component (#145)

docs/.vitepress/config.mts

@@ -46,8 +46,8 @@ export default defineConfigWithTheme({
                 link: '/pages/by-tag',
               },
               {
-                text: 'Info and Servers',
-                link: '/pages/info-servers',
+                text: 'Introduction',
+                link: '/pages/introduction',
               },
             ],
           },

docs/.vitepress/theme/components/sandbox/SandboxPreview.vue

@@ -86,6 +86,11 @@ watch(sandboxData.previewComponent, () => {
             :spec="sandboxData.spec.value"
             :is-dark="isDark"
           />
+          <OAIntroduction
+            v-else-if="sandboxData.previewComponent.value === 'OAIntroduction'"
+            :spec="sandboxData.spec.value"
+            :is-dark="isDark"
+          />
         </VPHomeContent>
       </div>
 

docs/.vitepress/theme/components/theme/ThemeConfig.vue

@@ -11,6 +11,7 @@ const themeConfig = useTheme()
 const availableComponents = [
   'OAOperation',
   'OASpec',
+  'OAIntroduction',
 ]
 
 const availableSidebarItemsTypes = [

docs/.vitepress/theme/sandboxData.ts

@@ -13,7 +13,7 @@ export interface SandboxData {
   sandboxView: Ref<'edit' | 'preview'>
   hideSandboxNav: Ref<boolean>
 
-  previewComponent: Ref<'OASpec' | 'OAOperation'>
+  previewComponent: Ref<'OASpec' | 'OAOperation' | 'OAIntroduction'>
   previewHeaders: Ref<Array<any>>
   operationId: Ref<string | null>
 

docs/guide/getting-started.md

@@ -26,19 +26,28 @@ Before you begin, make sure you have the following installed:
 
 ## Installation
 
-To install the theme in your VitePress project, run one of the following commands depending on your preferred package
-manager:
+Install the `vitepress-openapi` package using your package manager.
 
-```bash
-npm install vitepress-openapi
+::: code-group
 
-pnpm add vitepress-openapi
+```sh [npm]
+npm install vitepress-openapi
+```
 
+```sh [yarn]
 yarn add vitepress-openapi
+```
 
-bun install vitepress-openapi
+```sh [pnpm]
+pnpm add vitepress-openapi
+```
+
+```sh [bun]
+bun add vitepress-openapi
 ```
 
+:::
+
 ## Usage
 
 In your `.vitepress/theme/index.[js,ts]`, import the theme and the CSS file.

docs/pages/introduction.md

@@ -0,0 +1,79 @@
+---
+outline: 2
+---
+
+<script setup>
+import ScopeConfigurationTabs from '../.vitepress/theme/components/ScopeConfigurationTabs.vue'
+</script>
+
+# Introduction
+
+You can use the `OAIntroduction` component to display the OpenAPI `info` and `servers` sections.
+
+<ScopeConfigurationTabs>
+
+<template #global>
+
+If you have configured the OpenAPI Specification using the `useOpenapi` composable in your `.vitepress/theme/index.[js,ts]` file, you can just use the `OAIntroduction` component in any Markdown file.
+
+```markdown
+<OAIntroduction />
+```
+
+</template>
+
+<template #in-markdown>
+
+In your `.md` files, import the OpenAPI specification and pass it as `spec` prop to the `OAIntroduction` component.
+
+```markdown
+<script setup lang="ts">
+import spec from '../public/openapi.json'
+</script>
+
+<OAIntroduction :spec="spec" />
+```
+
+</template>
+
+</ScopeConfigurationTabs>
+
+## Example
+
+<SandboxIframe :sandbox-data="{sandboxView: 'preview', previewComponent: 'OAIntroduction', showSidebar: false}" :iframe-zoom="0.6" class="h-[70vh] max-h-[700px]" />
+
+## Info and Servers
+
+The `OAInfo` and `OAServers` components can be used separately to display the OpenAPI `info` and `servers` sections.
+
+<ScopeConfigurationTabs>
+
+<template #global>
+
+If you have configured the OpenAPI Specification using the `useOpenapi` composable in your `.vitepress/theme/index.[js,ts]` file, you can just use the `OAInfo` and `OAServers` components in any Markdown file.
+
+```markdown
+<OAInfo />
+
+<OAServers />
+```
+
+</template>
+
+<template #in-markdown>
+
+In your `.md` files, import the OpenAPI specification and pass it as `spec` prop to the `OAInfo` and `OAServers` components.
+
+```markdown
+<script setup lang="ts">
+import spec from '../public/openapi.json'
+</script>
+
+<OAInfo :spec="spec" />
+
+<OAServers :spec="spec" />
+```
+
+</template>
+
+</ScopeConfigurationTabs>

package.json

@@ -1,7 +1,7 @@
 {
   "name": "vitepress-openapi",
   "type": "module",
-  "version": "0.0.3-alpha.54",
+  "version": "0.0.3-alpha.55",
   "packageManager": "[email protected]",
   "homepage": "https://vitepress-openapi.vercel.app/",
   "repository": {

src/components/Common/OAIntroduction.vue

@@ -0,0 +1,25 @@
+<script setup>
+import { inject } from 'vue'
+import { getOpenApiInstance } from '../../lib/getOpenApiInstance'
+
+const props = defineProps({
+  spec: {
+    type: Object,
+    required: false,
+  },
+  openapi: {
+    type: Object,
+    required: false,
+  },
+})
+
+const openapi = props.openapi ?? getOpenApiInstance({
+  custom: { spec: props.spec },
+  injected: inject('openapi', undefined),
+})
+</script>
+
+<template>
+  <OAInfo :spec="spec" :openapi="openapi" />
+  <OAServers :spec="spec" :openapi="openapi" />
+</template>

src/components/index.ts

@@ -22,6 +22,7 @@ import OASchemaTabs from './Schema/OASchemaTabs.vue'
 import OASecurity from './Security/OASecurity.vue'
 import OAInfo from './Common/OAInfo.vue'
 import OAServers from './Common/OAServers.vue'
+import OAIntroduction from './Common/OAIntroduction.vue'
 import OALocaleSelect from './Common/OALocaleSelect.vue'
 import OARemoteSpec from './Remote/OARemoteSpec.vue'
 import OARemoteOperation from './Remote/OARemoteOperation.vue'
@@ -51,6 +52,7 @@ export {
   OASecurity,
   OAInfo,
   OAServers,
+  OAIntroduction,
   OALocaleSelect,
   OARemoteSpec,
   OARemoteOperation,