@dv.net/docs-vitepress-openapi 1.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (135) hide show
  1. package/README.md +52 -0
  2. package/dist/docs-vitepress-openapi.client.cjs.js +1 -0
  3. package/dist/docs-vitepress-openapi.client.es.js +16 -0
  4. package/dist/docs-vitepress-openapi.css +1 -0
  5. package/dist/docs-vitepress-openapi.node.cjs.js +4102 -0
  6. package/dist/docs-vitepress-openapi.node.es.js +72981 -0
  7. package/dist/vanilla-picker-BAEwS4Fy.js +536 -0
  8. package/dist/vanilla-picker-m653iADl.cjs +8 -0
  9. package/package.json +80 -0
  10. package/src/client.ts +73 -0
  11. package/src/components/Common/Lazy/OALazy.vue +49 -0
  12. package/src/components/Common/Lazy/lazyBus.ts +8 -0
  13. package/src/components/Common/OACodeBlock.vue +91 -0
  14. package/src/components/Common/OACodeValue.vue +22 -0
  15. package/src/components/Common/OAHeaderBadges.vue +44 -0
  16. package/src/components/Common/OAHeading.vue +84 -0
  17. package/src/components/Common/OAInfo.vue +106 -0
  18. package/src/components/Common/OAIntroduction.vue +25 -0
  19. package/src/components/Common/OAJSONEditor.vue +41 -0
  20. package/src/components/Common/OAMarkdown.vue +28 -0
  21. package/src/components/Common/OAMethodBadge.vue +20 -0
  22. package/src/components/Common/OAServers.vue +42 -0
  23. package/src/components/Operation/OAOperation.vue +345 -0
  24. package/src/components/Operation/OAOperationTags.vue +30 -0
  25. package/src/components/Parameter/OAParameter.vue +80 -0
  26. package/src/components/Parameter/OAParameterAttribute.vue +44 -0
  27. package/src/components/Parameter/OAParameterExamples.vue +52 -0
  28. package/src/components/Parameter/OAParameters.vue +69 -0
  29. package/src/components/Path/OAPath.vue +347 -0
  30. package/src/components/Path/OAPathEndpoint.vue +99 -0
  31. package/src/components/Path/OAPaths.vue +62 -0
  32. package/src/components/Path/OAPathsByTag.vue +118 -0
  33. package/src/components/Path/OAPathsByTags.vue +99 -0
  34. package/src/components/Path/OAPathsSummary.vue +52 -0
  35. package/src/components/Playground/OAPlaygroundParameterInput.vue +97 -0
  36. package/src/components/Playground/OAPlaygroundParameters.vue +262 -0
  37. package/src/components/Playground/OAPlaygroundResponse.vue +74 -0
  38. package/src/components/Playground/OAPlaygroundSecurityInput.vue +44 -0
  39. package/src/components/Remote/OARemoteContext.vue +42 -0
  40. package/src/components/Remote/OARemoteOperation.vue +30 -0
  41. package/src/components/Remote/OARemoteRoot.vue +29 -0
  42. package/src/components/Remote/OARemoteSpec.vue +23 -0
  43. package/src/components/Request/OARequestBody.vue +24 -0
  44. package/src/components/Response/OAResponse.vue +81 -0
  45. package/src/components/Response/OAResponses.vue +119 -0
  46. package/src/components/Sample/OACodeSamples.vue +71 -0
  47. package/src/components/Schema/OASchemaPropertyAttributes.vue +44 -0
  48. package/src/components/Schema/OASchemaTabs.vue +90 -0
  49. package/src/components/Schema/OASchemaUI.vue +151 -0
  50. package/src/components/Security/OASecurity.vue +79 -0
  51. package/src/components/Security/OASecurityContent.vue +100 -0
  52. package/src/components/Spec/OASpec.vue +127 -0
  53. package/src/components/Spec/OASpecSkeleton.vue +26 -0
  54. package/src/components/Try/OATryItButton.vue +171 -0
  55. package/src/components/Try/OATryWithVariables.vue +105 -0
  56. package/src/components/index.ts +55 -0
  57. package/src/components/ui/badge/Badge.vue +18 -0
  58. package/src/components/ui/badge/index.ts +32 -0
  59. package/src/components/ui/button/Button.vue +28 -0
  60. package/src/components/ui/button/index.ts +37 -0
  61. package/src/components/ui/checkbox/Checkbox.vue +33 -0
  62. package/src/components/ui/checkbox/index.ts +1 -0
  63. package/src/components/ui/collapsible/Collapsible.vue +18 -0
  64. package/src/components/ui/collapsible/CollapsibleContent.vue +15 -0
  65. package/src/components/ui/collapsible/CollapsibleTrigger.vue +12 -0
  66. package/src/components/ui/collapsible/index.ts +3 -0
  67. package/src/components/ui/input/Input.vue +29 -0
  68. package/src/components/ui/input/index.ts +1 -0
  69. package/src/components/ui/label/Label.vue +29 -0
  70. package/src/components/ui/label/index.ts +1 -0
  71. package/src/components/ui/multiselect/Multiselect.vue +104 -0
  72. package/src/components/ui/select/Select.vue +15 -0
  73. package/src/components/ui/select/SelectContent.vue +56 -0
  74. package/src/components/ui/select/SelectGroup.vue +24 -0
  75. package/src/components/ui/select/SelectItem.vue +40 -0
  76. package/src/components/ui/select/SelectItemText.vue +12 -0
  77. package/src/components/ui/select/SelectLabel.vue +14 -0
  78. package/src/components/ui/select/SelectScrollDownButton.vue +29 -0
  79. package/src/components/ui/select/SelectScrollUpButton.vue +29 -0
  80. package/src/components/ui/select/SelectSeparator.vue +22 -0
  81. package/src/components/ui/select/SelectTrigger.vue +33 -0
  82. package/src/components/ui/select/SelectValue.vue +12 -0
  83. package/src/components/ui/select/index.ts +11 -0
  84. package/src/components/ui/tabs/Tabs.vue +15 -0
  85. package/src/components/ui/tabs/TabsContent.vue +24 -0
  86. package/src/components/ui/tabs/TabsList.vue +27 -0
  87. package/src/components/ui/tabs/TabsTrigger.vue +33 -0
  88. package/src/components/ui/tabs/index.ts +21 -0
  89. package/src/composables/useOpenapi.ts +70 -0
  90. package/src/composables/usePaths.ts +31 -0
  91. package/src/composables/usePlayground.ts +49 -0
  92. package/src/composables/useShiki.ts +46 -0
  93. package/src/composables/useSidebar.ts +301 -0
  94. package/src/composables/useTheme.ts +799 -0
  95. package/src/index.ts +8 -0
  96. package/src/json.css +251 -0
  97. package/src/lib/OpenApi.ts +254 -0
  98. package/src/lib/codeSamples/buildRequest.ts +149 -0
  99. package/src/lib/codeSamples/generateCodeSample.ts +20 -0
  100. package/src/lib/codeSamples/generateCodeSampleCurl.ts +150 -0
  101. package/src/lib/codeSamples/generateCodeSampleJavaScript.ts +29 -0
  102. package/src/lib/codeSamples/generateCodeSamplePhp.ts +50 -0
  103. package/src/lib/codeSamples/generateCodeSamplePython.ts +32 -0
  104. package/src/lib/codeSamples/request.ts +25 -0
  105. package/src/lib/constraintsParser.ts +30 -0
  106. package/src/lib/createOpenApiInstance.ts +18 -0
  107. package/src/lib/deepUnref.ts +76 -0
  108. package/src/lib/examples/getPropertyExample.ts +31 -0
  109. package/src/lib/examples/getPropertyExamples.ts +27 -0
  110. package/src/lib/examples/getSchemaExample.ts +38 -0
  111. package/src/lib/examples/getSchemaUiJson.ts +150 -0
  112. package/src/lib/examples/getSchemaUiXml.ts +9 -0
  113. package/src/lib/examples/hasExample.ts +26 -0
  114. package/src/lib/getOpenApiInstance.ts +39 -0
  115. package/src/lib/getSchemaUi.ts +280 -0
  116. package/src/lib/getSecurityUi.ts +33 -0
  117. package/src/lib/operationData.ts +24 -0
  118. package/src/lib/prepareOpenAPI/generateMissingOperationIds.ts +19 -0
  119. package/src/lib/prepareOpenAPI/generateMissingSummary.ts +20 -0
  120. package/src/lib/prepareOpenAPI/generateMissingTags.ts +36 -0
  121. package/src/lib/prepareOpenAPI/prepareOpenAPI.ts +35 -0
  122. package/src/lib/processOpenAPI.ts +131 -0
  123. package/src/lib/resolveCircularRef.ts +66 -0
  124. package/src/lib/sidebar/cleanSidebarItems.ts +19 -0
  125. package/src/lib/sidebar/ensureGroupTextSlashPrefix.ts +18 -0
  126. package/src/lib/sidebar/flatSidebarItems.ts +58 -0
  127. package/src/lib/sidebar/generateSidebarItemsByPaths.ts +132 -0
  128. package/src/lib/sidebar/mergeAdjacentGroups.ts +56 -0
  129. package/src/lib/sidebar/setItemCollapsedState.ts +15 -0
  130. package/src/lib/utils.ts +7 -0
  131. package/src/locales/en.json +50 -0
  132. package/src/locales/index.ts +4 -0
  133. package/src/style.css +180 -0
  134. package/src/types.ts +73 -0
  135. package/src/vite-env.d.ts +8 -0
@@ -0,0 +1,11 @@
1
+ export { default as Select } from './Select.vue'
2
+ export { default as SelectContent } from './SelectContent.vue'
3
+ export { default as SelectGroup } from './SelectGroup.vue'
4
+ export { default as SelectItem } from './SelectItem.vue'
5
+ export { default as SelectItemText } from './SelectItemText.vue'
6
+ export { default as SelectLabel } from './SelectLabel.vue'
7
+ export { default as SelectScrollDownButton } from './SelectScrollDownButton.vue'
8
+ export { default as SelectScrollUpButton } from './SelectScrollUpButton.vue'
9
+ export { default as SelectSeparator } from './SelectSeparator.vue'
10
+ export { default as SelectTrigger } from './SelectTrigger.vue'
11
+ export { default as SelectValue } from './SelectValue.vue'
@@ -0,0 +1,15 @@
1
+ <script setup lang="ts">
2
+ import type { TabsRootEmits, TabsRootProps } from 'radix-vue'
3
+ import { TabsRoot, useForwardPropsEmits } from 'radix-vue'
4
+
5
+ const props = defineProps<TabsRootProps>()
6
+ const emits = defineEmits<TabsRootEmits>()
7
+
8
+ const forwarded = useForwardPropsEmits(props, emits)
9
+ </script>
10
+
11
+ <template>
12
+ <TabsRoot v-bind="forwarded">
13
+ <slot />
14
+ </TabsRoot>
15
+ </template>
@@ -0,0 +1,24 @@
1
+ <script setup lang="ts">
2
+ import type { TabsContentProps } from 'radix-vue'
3
+ import type { HTMLAttributes } from 'vue'
4
+ import { TabsContent } from 'radix-vue'
5
+ import { computed } from 'vue'
6
+ import { cn } from '../../../lib/utils'
7
+
8
+ const props = defineProps<TabsContentProps & { class?: HTMLAttributes['class'] }>()
9
+
10
+ const delegatedProps = computed(() => {
11
+ const { class: _, ...delegated } = props
12
+
13
+ return delegated
14
+ })
15
+ </script>
16
+
17
+ <template>
18
+ <TabsContent
19
+ :class="cn('mt-2 ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2', props.class)"
20
+ v-bind="delegatedProps"
21
+ >
22
+ <slot />
23
+ </TabsContent>
24
+ </template>
@@ -0,0 +1,27 @@
1
+ <script setup lang="ts">
2
+ import type { TabsListProps } from 'radix-vue'
3
+ import type { HTMLAttributes } from 'vue'
4
+ import { TabsList } from 'radix-vue'
5
+ import { computed } from 'vue'
6
+ import { cn } from '../../../lib/utils'
7
+
8
+ const props = defineProps<TabsListProps & { class?: HTMLAttributes['class'] }>()
9
+
10
+ const delegatedProps = computed(() => {
11
+ const { class: _, ...delegated } = props
12
+
13
+ return delegated
14
+ })
15
+ </script>
16
+
17
+ <template>
18
+ <TabsList
19
+ v-bind="delegatedProps"
20
+ :class="cn(
21
+ 'inline-flex h-10 items-center justify-center rounded-md bg-muted p-1 text-muted-foreground',
22
+ props.class,
23
+ )"
24
+ >
25
+ <slot />
26
+ </TabsList>
27
+ </template>
@@ -0,0 +1,33 @@
1
+ <script setup lang="ts">
2
+ import type { TabsTriggerProps } from 'radix-vue'
3
+ import type { HTMLAttributes } from 'vue'
4
+ import type { TabsTriggerVariants } from './index'
5
+ import { TabsTrigger, useForwardProps } from 'radix-vue'
6
+ import { computed } from 'vue'
7
+ import { cn } from '../../../lib/utils'
8
+ import { tabsTriggerVariants } from './index'
9
+
10
+ interface Props extends TabsTriggerProps {
11
+ variant?: TabsTriggerVariants['variant']
12
+ class?: HTMLAttributes['class']
13
+ }
14
+
15
+ const props = withDefaults(defineProps<Props>(), {})
16
+
17
+ const delegatedProps = computed(() => {
18
+ const { class: _, ...delegated } = props
19
+
20
+ return delegated
21
+ })
22
+
23
+ const forwardedProps = useForwardProps(delegatedProps)
24
+ </script>
25
+
26
+ <template>
27
+ <TabsTrigger
28
+ v-bind="forwardedProps"
29
+ :class="cn(tabsTriggerVariants({ variant }), props.class)"
30
+ >
31
+ <slot />
32
+ </TabsTrigger>
33
+ </template>
@@ -0,0 +1,21 @@
1
+ import type { VariantProps } from 'class-variance-authority'
2
+ import { cva } from 'class-variance-authority'
3
+
4
+ export { default as Tabs } from './Tabs.vue'
5
+ export { default as TabsContent } from './TabsContent.vue'
6
+ export { default as TabsList } from './TabsList.vue'
7
+ export { default as TabsTrigger } from './TabsTrigger.vue'
8
+
9
+ export const tabsTriggerVariants = cva(
10
+ 'inline-flex items-center justify-center whitespace-nowrap rounded-sm px-3 py-1.5 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
11
+ {
12
+ variants: {
13
+ variant: {
14
+ default: 'data-[state=active]:text-foreground',
15
+ select: 'relative flex w-full',
16
+ schemaTabs: 'data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm',
17
+ },
18
+ },
19
+ },
20
+ )
21
+ export type TabsTriggerVariants = VariantProps<typeof tabsTriggerVariants>
@@ -0,0 +1,70 @@
1
+ import type { OpenAPI } from '@scalar/openapi-types'
2
+ import type { PartialUseThemeConfig } from './useTheme'
3
+ import { createOpenApiInstance } from '../lib/createOpenApiInstance'
4
+ import { useTheme } from './useTheme'
5
+
6
+ export interface OpenAPIData {
7
+ id: string
8
+ spec: OpenAPI.Document
9
+ openapi: ReturnType<typeof createOpenApiInstance>
10
+ config?: PartialUseThemeConfig
11
+ }
12
+
13
+ export type Schemas = Map<string, OpenAPIData>
14
+
15
+ export const DEFAULT_SCHEMA = 'main'
16
+
17
+ const schemas: Schemas = new Map()
18
+
19
+ let mainSchema: OpenAPI.Document | null = null
20
+
21
+ export function useOpenapi({
22
+ spec,
23
+ config,
24
+ }: {
25
+ spec?: OpenAPI.Document
26
+ config?: PartialUseThemeConfig
27
+ } = {}) {
28
+ if (config) {
29
+ useTheme(config)
30
+ }
31
+
32
+ if (spec) {
33
+ setupOpenApi({ spec, config })
34
+ }
35
+
36
+ /**
37
+ * @deprecated Use `useOpenapi({ spec })` instead.
38
+ */
39
+ function setSpec(value: OpenAPI.Document) {
40
+ console.warn('Deprecated usage of `setSpec`. Use `useOpenapi({ spec })` instead.')
41
+ setupOpenApi({ spec: value })
42
+ }
43
+
44
+ function setupOpenApi({ spec, config }: { spec: OpenAPI.Document, config?: PartialUseThemeConfig }) {
45
+ addSchema({ id: DEFAULT_SCHEMA, spec, config })
46
+ mainSchema = (schemas.get(DEFAULT_SCHEMA) ?? {}) as OpenAPI.Document
47
+ }
48
+
49
+ function addSchema({ id, spec, config }: { id: string, spec: OpenAPI.Document, config?: PartialUseThemeConfig }) {
50
+ const openapi = createOpenApiInstance({
51
+ spec,
52
+ defaultTag: config?.spec?.defaultTag,
53
+ defaultTagDescription: config?.spec?.defaultTagDescription,
54
+ })
55
+
56
+ // @ts-expect-error: This adds all the properties of the OpenAPI instance to the schema.
57
+ schemas.set(id, {
58
+ ...openapi,
59
+ id,
60
+ config,
61
+ })
62
+ }
63
+
64
+ return {
65
+ ...mainSchema,
66
+ json: mainSchema?.spec,
67
+ setSpec,
68
+ schemas,
69
+ }
70
+ }
@@ -0,0 +1,31 @@
1
+ import type { OpenAPI } from '@scalar/openapi-types'
2
+ import { OpenApi } from '../lib/OpenApi'
3
+ import { prepareOpenAPI } from '../lib/prepareOpenAPI/prepareOpenAPI'
4
+
5
+ export function usePaths({
6
+ spec,
7
+ defaultTag = undefined,
8
+ defaultTagDescription = undefined,
9
+ }: {
10
+ spec: OpenAPI.Document
11
+ defaultTag?: string
12
+ defaultTagDescription?: string
13
+ }) {
14
+ const openapi = OpenApi({
15
+ spec,
16
+ transformedSpec: prepareOpenAPI({
17
+ spec,
18
+ defaultTag,
19
+ defaultTagDescription,
20
+ }),
21
+ })
22
+
23
+ function getTags() {
24
+ return openapi.getFilteredTags()
25
+ }
26
+
27
+ return {
28
+ getPathsByVerbs: openapi.getPathsByVerbs,
29
+ getTags,
30
+ }
31
+ }
@@ -0,0 +1,49 @@
1
+ import type { OpenAPIV3 } from '@scalar/openapi-types'
2
+
3
+ interface SecuritySchemeDefaultValues {
4
+ 'http-basic': string
5
+ 'http-bearer': string
6
+ 'apiKey': string | null
7
+ 'openIdConnect': string
8
+ 'oauth2': string
9
+ }
10
+
11
+ let securitySchemeDefaultValues: SecuritySchemeDefaultValues = {
12
+ 'http-basic': 'Basic Auth',
13
+ 'http-bearer': 'Bearer Token',
14
+ 'apiKey': null,
15
+ 'openIdConnect': 'OpenID Connect',
16
+ 'oauth2': 'OAuth2 Token',
17
+ }
18
+
19
+ export function usePlayground() {
20
+ function setSecuritySchemeDefaultValues(values: Partial<SecuritySchemeDefaultValues>) {
21
+ securitySchemeDefaultValues = {
22
+ ...securitySchemeDefaultValues,
23
+ ...values,
24
+ }
25
+ }
26
+
27
+ function getSecuritySchemeDefaultValue(scheme: OpenAPIV3.SecuritySchemeObject) {
28
+ if (scheme.type === 'http') {
29
+ const schemeKey = scheme.scheme === 'basic' ? 'http-basic' : 'http-bearer'
30
+ return securitySchemeDefaultValues[schemeKey]
31
+ }
32
+
33
+ const schemeType = scheme.type as keyof SecuritySchemeDefaultValues
34
+ if (Object.keys(securitySchemeDefaultValues).includes(schemeType) && securitySchemeDefaultValues[schemeType] !== null) {
35
+ return securitySchemeDefaultValues[schemeType] ?? ''
36
+ }
37
+
38
+ if (scheme.type === 'apiKey' && scheme.name) {
39
+ return scheme.name
40
+ }
41
+
42
+ return ''
43
+ }
44
+
45
+ return {
46
+ setSecuritySchemeDefaultValues,
47
+ getSecuritySchemeDefaultValue,
48
+ }
49
+ }
@@ -0,0 +1,46 @@
1
+ import type { HighlighterCore } from 'shiki'
2
+ import { createHighlighterCoreSync } from 'shiki/core'
3
+ import { createJavaScriptRegexEngine } from 'shiki/engine/javascript'
4
+ import bash from 'shiki/langs/bash.mjs'
5
+ import js from 'shiki/langs/javascript.mjs'
6
+ import json from 'shiki/langs/json.mjs'
7
+ import markdown from 'shiki/langs/markdown.mjs'
8
+ import php from 'shiki/langs/php.mjs'
9
+ import python from 'shiki/langs/python.mjs'
10
+ import ts from 'shiki/langs/typescript.mjs'
11
+ import xml from 'shiki/langs/xml.mjs'
12
+ import { ref } from 'vue'
13
+ import { useTheme } from './useTheme'
14
+
15
+ const langs = [js, ts, markdown, json, xml, python, bash, php]
16
+
17
+ let shiki: HighlighterCore | null = null
18
+
19
+ const loading = ref(true)
20
+ const themeConfig = useTheme()
21
+
22
+ export function useShiki() {
23
+ const initShiki = () => {
24
+ if (shiki) {
25
+ return
26
+ }
27
+ shiki = createHighlighterCoreSync({
28
+ themes: [themeConfig.getHighlighterTheme()?.light, themeConfig.getHighlighterTheme()?.dark],
29
+ langs,
30
+ engine: createJavaScriptRegexEngine(),
31
+ })
32
+ }
33
+
34
+ const renderShiki = (content: string, { lang, theme }: { lang: string, theme: string }) => {
35
+ if (shiki && shiki.getLoadedLanguages().includes(lang)) {
36
+ return shiki.codeToHtml(content, {
37
+ lang,
38
+ theme,
39
+ })
40
+ } else {
41
+ return `<pre><code>${content}</code></pre>`
42
+ }
43
+ }
44
+
45
+ return { loading, renderShiki, initShiki }
46
+ }
@@ -0,0 +1,301 @@
1
+ import type { OpenAPI, OpenAPIV3 } from '@scalar/openapi-types'
2
+ import type { DefaultTheme } from 'vitepress'
3
+ import { httpVerbs } from '../index'
4
+ import { OpenApi } from '../lib/OpenApi'
5
+ import { prepareOpenAPI } from '../lib/prepareOpenAPI/prepareOpenAPI'
6
+ import { cleanSidebarItems } from '../lib/sidebar/cleanSidebarItems'
7
+ import { generateSidebarItemsByPaths } from '../lib/sidebar/generateSidebarItemsByPaths'
8
+
9
+ type MethodAliases = Record<string, string>
10
+
11
+ export type SidebarItemTemplateFn = (
12
+ method: OpenAPIV3.HttpMethods,
13
+ path: string
14
+ ) => string
15
+
16
+ export type SidebarGroupTemplateFn = (
17
+ path: string,
18
+ depth: number
19
+ ) => string
20
+
21
+ export interface SidebarConfig {
22
+ spec?: OpenAPI.Document | null
23
+ linkPrefix?: string
24
+ tagLinkPrefix?: string
25
+ defaultTag?: string
26
+ methodAliases?: MethodAliases
27
+ sidebarItemTemplate?: SidebarItemTemplateFn
28
+ sidebarGroupTemplate?: SidebarGroupTemplateFn
29
+ }
30
+
31
+ export interface SidebarGroupConfig {
32
+ tag: string | string[]
33
+ text?: string
34
+ linkPrefix?: string
35
+ addedOperations?: Set<string>
36
+ sidebarItemTemplate?: SidebarItemTemplateFn
37
+ sidebarGroupTemplate?: SidebarGroupTemplateFn
38
+ }
39
+
40
+ export interface SidebarGroupsConfig {
41
+ tags?: string[] | null
42
+ linkPrefix?: string | null
43
+ sidebarItemTemplate?: SidebarItemTemplateFn
44
+ sidebarGroupTemplate?: SidebarGroupTemplateFn
45
+ }
46
+
47
+ export interface OASidebarItem extends DefaultTheme.SidebarItem {
48
+ path?: string
49
+ isOperation?: boolean
50
+ flattenedItems?: OASidebarItem[]
51
+ }
52
+
53
+ interface OpenAPIOperation extends OpenAPIV3.OperationObject {
54
+ 'x-sidebar-title'?: string
55
+ 'operationId': string
56
+ }
57
+
58
+ const DEFAULT_CONFIG: Required<Omit<SidebarConfig, 'methodAliases' | 'spec' | 'sidebarItemTemplate' | 'sidebarGroupTemplate'>> = {
59
+ linkPrefix: '/operations/',
60
+ tagLinkPrefix: '/tags/',
61
+ defaultTag: 'Default',
62
+ } as const
63
+
64
+ function defaultGroupTemplate(path: string, _: number = 1): string {
65
+ return path
66
+ }
67
+
68
+ export function useSidebar({
69
+ spec,
70
+ linkPrefix = DEFAULT_CONFIG.linkPrefix,
71
+ tagLinkPrefix = DEFAULT_CONFIG.tagLinkPrefix,
72
+ defaultTag = DEFAULT_CONFIG.defaultTag,
73
+ methodAliases = {},
74
+ sidebarItemTemplate,
75
+ sidebarGroupTemplate,
76
+ }: SidebarConfig = {}) {
77
+ let openApiInstance: ReturnType<typeof OpenApi> | null = null
78
+
79
+ function getOpenApi() {
80
+ if (!spec) {
81
+ throw new Error('OpenAPI spec is not provided.')
82
+ }
83
+
84
+ if (!openApiInstance) {
85
+ openApiInstance = OpenApi({
86
+ spec,
87
+ transformedSpec: prepareOpenAPI({
88
+ spec,
89
+ defaultTag,
90
+ }),
91
+ })
92
+ }
93
+
94
+ return openApiInstance
95
+ }
96
+
97
+ const _globalItemTemplate: SidebarItemTemplateFn = sidebarItemTemplate || ((method, title) => {
98
+ const resolvedMethod = methodAliases[method] || method.toUpperCase()
99
+ return `<span class="OASidebarItem group/oaSidebarItem">
100
+ <span class="OASidebarItem-badge OAMethodBadge--${method.toLowerCase()}">${resolvedMethod}</span>
101
+ <span class="OASidebarItem-text text">${title}</span>
102
+ </span>`
103
+ })
104
+
105
+ const _globalGroupTemplate: SidebarGroupTemplateFn = sidebarGroupTemplate || defaultGroupTemplate
106
+
107
+ function sidebarItemTemplateForMethodPath(
108
+ method: OpenAPIV3.HttpMethods,
109
+ path: string,
110
+ localItemTemplate?: SidebarItemTemplateFn,
111
+ ): string {
112
+ const operation = getOpenApi().getPaths()?.[path]?.[method] as OpenAPIOperation | undefined
113
+ if (!operation) {
114
+ return `[${method.toUpperCase()}] ${path}`
115
+ }
116
+
117
+ const { summary } = operation
118
+
119
+ const sidebarTitle = operation['x-sidebar-title'] || summary || `${method.toUpperCase()} ${path}`
120
+
121
+ const finalTemplate = localItemTemplate || _globalItemTemplate
122
+
123
+ return finalTemplate(method, sidebarTitle)
124
+ }
125
+
126
+ function generateSidebarItem(
127
+ method: OpenAPIV3.HttpMethods,
128
+ path: string,
129
+ itemLinkPrefix: string = linkPrefix,
130
+ localItemTemplate?: SidebarItemTemplateFn,
131
+ ): OASidebarItem | null {
132
+ const operation = getOpenApi().getPaths()?.[path]?.[method] as OpenAPIOperation | undefined
133
+
134
+ if (!operation) {
135
+ return null
136
+ }
137
+
138
+ const operationId = operation.operationId
139
+
140
+ return {
141
+ text: sidebarItemTemplateForMethodPath(method, path, localItemTemplate),
142
+ link: `${itemLinkPrefix}${operationId}`,
143
+ }
144
+ }
145
+
146
+ function generateSidebarGroup({
147
+ tag,
148
+ text = '',
149
+ linkPrefix: groupLinkPrefix = linkPrefix,
150
+ addedOperations = new Set<string>(),
151
+ sidebarItemTemplate: localItemTemplate,
152
+ sidebarGroupTemplate: localGroupTemplate,
153
+ }: SidebarGroupConfig): OASidebarItem {
154
+ const paths = getOpenApi().getPaths()
155
+
156
+ if (!paths || tag.length === 0) {
157
+ return {
158
+ text: '',
159
+ items: [],
160
+ }
161
+ }
162
+
163
+ const includeTags = Array.isArray(tag) ? tag : [tag]
164
+
165
+ const items = Object.entries(paths)
166
+ .flatMap(([path, pathObject]) =>
167
+ httpVerbs
168
+ .map((method) => {
169
+ const operation = pathObject?.[method] as OpenAPIOperation | undefined
170
+
171
+ if (!operation || addedOperations.has(operation.operationId + tag)) {
172
+ return null
173
+ }
174
+
175
+ const shouldInclude
176
+ = includeTags.length === 0
177
+ || includeTags.every(tagName => operation.tags?.includes(tagName))
178
+
179
+ if (shouldInclude) {
180
+ addedOperations.add(operation.operationId + tag)
181
+ return generateSidebarItem(method as OpenAPIV3.HttpMethods, path, groupLinkPrefix, localItemTemplate)
182
+ }
183
+
184
+ return null
185
+ })
186
+ .filter((item): item is OASidebarItem => item !== null),
187
+ )
188
+
189
+ const finalGroupTemplate = localGroupTemplate || _globalGroupTemplate
190
+
191
+ return {
192
+ text: finalGroupTemplate(text, 0),
193
+ items,
194
+ }
195
+ }
196
+
197
+ function generateSidebarGroups({
198
+ tags = undefined,
199
+ linkPrefix: groupsLinkPrefix = linkPrefix,
200
+ sidebarItemTemplate: localItemTemplate,
201
+ sidebarGroupTemplate: localGroupTemplate,
202
+ }: SidebarGroupsConfig = {}): OASidebarItem[] {
203
+ if (tags === undefined) {
204
+ tags = getOpenApi().getOperationsTags()
205
+ }
206
+
207
+ if (!getOpenApi().getPaths()) {
208
+ return []
209
+ }
210
+
211
+ const addedOperations = new Set<string>()
212
+
213
+ const taggedGroups = (tags ?? []).map(tag =>
214
+ generateSidebarGroup({
215
+ tag,
216
+ text: tag,
217
+ linkPrefix: groupsLinkPrefix || tagLinkPrefix,
218
+ addedOperations,
219
+ sidebarItemTemplate: localItemTemplate,
220
+ sidebarGroupTemplate: localGroupTemplate,
221
+ }),
222
+ )
223
+
224
+ const untaggedGroup = generateSidebarGroup({
225
+ tag: [],
226
+ text: '',
227
+ linkPrefix: groupsLinkPrefix || tagLinkPrefix,
228
+ addedOperations,
229
+ sidebarItemTemplate: localItemTemplate,
230
+ sidebarGroupTemplate: localGroupTemplate,
231
+ })
232
+
233
+ return untaggedGroup.items?.length
234
+ ? [...taggedGroups, untaggedGroup]
235
+ : taggedGroups
236
+ }
237
+
238
+ function itemsByTags({
239
+ tags = undefined,
240
+ linkPrefix: tagsLinkPrefix = tagLinkPrefix,
241
+ }: SidebarGroupsConfig = {}): OASidebarItem[] {
242
+ if (tags === undefined) {
243
+ tags = getOpenApi().getFilteredTags().map((tag: OpenAPIV3.TagObject) => tag.name || '')
244
+ }
245
+
246
+ if (!getOpenApi().getPaths() || !tags) {
247
+ return []
248
+ }
249
+
250
+ return tags.map(tag => ({
251
+ text: tag,
252
+ link: `${tagsLinkPrefix}${tag}`,
253
+ }))
254
+ }
255
+
256
+ function itemsByPaths({
257
+ startsWith = '',
258
+ collapsible = true,
259
+ depth = 6,
260
+ linkPrefix: itemLinkPrefix = linkPrefix,
261
+ sidebarItemTemplate,
262
+ sidebarGroupTemplate,
263
+ }: {
264
+ startsWith?: string
265
+ collapsible?: boolean
266
+ depth?: number
267
+ linkPrefix?: string
268
+ sidebarItemTemplate?: SidebarItemTemplateFn
269
+ sidebarGroupTemplate?: SidebarGroupTemplateFn
270
+ } = {}): DefaultTheme.SidebarItem[] {
271
+ const paths = getOpenApi().getPaths()
272
+
273
+ const itemTemplateForMethodPath = (
274
+ method: OpenAPIV3.HttpMethods,
275
+ path: string,
276
+ ) => sidebarItemTemplateForMethodPath(method, path, sidebarItemTemplate)
277
+
278
+ const sidebarItems = generateSidebarItemsByPaths({
279
+ paths,
280
+ startsWith,
281
+ collapsible,
282
+ depth,
283
+ itemLinkPrefix,
284
+ sidebarItemTemplate: itemTemplateForMethodPath,
285
+ sidebarGroupTemplate,
286
+ })
287
+
288
+ return cleanSidebarItems(sidebarItems) as DefaultTheme.SidebarItem[]
289
+ }
290
+
291
+ return {
292
+ sidebarItemTemplate: _globalItemTemplate,
293
+ sidebarGroupTemplate: _globalGroupTemplate,
294
+ generateSidebarItem,
295
+ generateSidebarGroup,
296
+ generateSidebarGroups,
297
+ itemsByTags,
298
+ itemsByPaths,
299
+ // TODO: Add `itemsByOperations` function
300
+ }
301
+ }