@scalar/api-reference 0.1.1

package/src/components/Content/ReferenceEndpoint/ExampleRequest.vue

@@ -0,0 +1,363 @@
+<script setup lang="ts">
+import { java } from '@codemirror/lang-java'
+import { javascript } from '@codemirror/lang-javascript'
+import { python } from '@codemirror/lang-python'
+import { type LanguageSupport } from '@codemirror/language'
+import { StreamLanguage } from '@codemirror/language'
+import {
+  c,
+  csharp,
+  kotlin,
+  objectiveC,
+} from '@codemirror/legacy-modes/mode/clike'
+import { clojure } from '@codemirror/legacy-modes/mode/clojure'
+import { go } from '@codemirror/legacy-modes/mode/go'
+import { http } from '@codemirror/legacy-modes/mode/http'
+import { oCaml } from '@codemirror/legacy-modes/mode/mllike'
+import { powerShell } from '@codemirror/legacy-modes/mode/powershell'
+import { r } from '@codemirror/legacy-modes/mode/r'
+import { ruby } from '@codemirror/legacy-modes/mode/ruby'
+import { shell } from '@codemirror/legacy-modes/mode/shell'
+import { swift } from '@codemirror/legacy-modes/mode/swift'
+import { lineNumbers } from '@codemirror/view'
+import {
+  generateRequest,
+  useApiClientRequestStore,
+  useApiClientStore,
+} from '@scalar/api-client'
+import { useOperation } from '@scalar/api-client'
+import { useClipboard } from '@scalar/use-clipboard'
+import { useCodeMirror } from '@scalar/use-codemirror'
+import { EditorView } from 'codemirror'
+import {
+  HTTPSnippet,
+  type HarRequest,
+  type TargetId,
+  availableTargets,
+} from 'httpsnippet-lite'
+import { computed, onMounted, watch } from 'vue'
+
+import {
+  generateAxiosCodeFromRequest,
+  generateLaravelCodeFromRequest,
+} from '../../../helpers'
+import { useTemplateStore } from '../../../stores/template'
+import type { Operation, Server } from '../../../types'
+import { Card, CardContent, CardFooter, CardHeader } from '../../Card'
+import { Icon } from '../../Icon'
+
+const props = defineProps<{ operation: Operation; server: Server }>()
+
+const { copyToClipboard } = useClipboard()
+
+const { setActiveRequest } = useApiClientRequestStore()
+
+const { toggleApiClient } = useApiClientStore()
+
+const {
+  state: templateState,
+  getLanguageTitleByKey,
+  setItem,
+} = useTemplateStore()
+
+// TODO: Add PHP
+const syntaxHighlighting: Record<
+  Exclude<TargetId, 'php'> | 'axios',
+  LanguageSupport | StreamLanguage<any>
+> = {
+  c: StreamLanguage.define(c),
+  clojure: StreamLanguage.define(clojure),
+  csharp: StreamLanguage.define(csharp),
+  go: StreamLanguage.define(go),
+  http: StreamLanguage.define(http),
+  java: java(),
+  javascript: javascript(),
+  kotlin: StreamLanguage.define(kotlin),
+  node: javascript(),
+  objc: StreamLanguage.define(objectiveC),
+  ocaml: StreamLanguage.define(oCaml),
+  powershell: StreamLanguage.define(powerShell),
+  python: python(),
+  r: StreamLanguage.define(r),
+  ruby: StreamLanguage.define(ruby),
+  shell: StreamLanguage.define(shell),
+  swift: StreamLanguage.define(swift),
+  axios: javascript(),
+}
+
+const editorExtensions = computed(() => {
+  const extensions = [lineNumbers(), EditorView.editable.of(false)]
+
+  if (
+    Object.hasOwnProperty.call(
+      syntaxHighlighting,
+      templateState.preferredLanguage,
+    )
+  ) {
+    // @ts-ignore
+    extensions.push(syntaxHighlighting[templateState.preferredLanguage])
+  }
+
+  return extensions
+})
+
+const { codeMirrorRef, setCodeMirrorContent, reconfigureCodeMirror } =
+  useCodeMirror({
+    content: '',
+    extensions: editorExtensions.value,
+    forceDarkMode: true,
+  })
+
+const { parameterMap } = useOperation(props)
+
+async function generateSnippet() {
+  if (templateState.preferredLanguage === 'axios') {
+    return generateAxiosCodeFromRequest({
+      method: props.operation.httpVerb.toUpperCase(),
+      url: `${props.server.url}${props.operation.path}`,
+    })
+  } else if (templateState.preferredLanguage === 'laravel') {
+    return generateLaravelCodeFromRequest({
+      method: props.operation.httpVerb.toUpperCase(),
+      url: `${props.server.url}${props.operation.path}`,
+    })
+  }
+
+  try {
+    const snippet = new HTTPSnippet({
+      method: props.operation.httpVerb.toUpperCase(),
+      url: `${props.server.url}${props.operation.path}`,
+    } as HarRequest)
+    const output = (await snippet.convert(
+      templateState.preferredLanguage as TargetId,
+    )) as string
+    return output
+  } catch {
+    const snippet = new HTTPSnippet({
+      method: props.operation.httpVerb.toUpperCase(),
+      url: `${window.location.origin}${props.operation.path}`,
+    } as HarRequest)
+    const output = (await snippet.convert(
+      templateState.preferredLanguage as TargetId,
+    )) as string
+
+    return output
+  }
+}
+
+onMounted(async () => {
+  const initialSnippet = await generateSnippet()
+  setCodeMirrorContent(initialSnippet)
+  watch(
+    () => templateState.preferredLanguage,
+    async () => {
+      const output = await generateSnippet()
+      setCodeMirrorContent(output)
+      reconfigureCodeMirror(editorExtensions.value)
+    },
+  )
+})
+
+const copyExampleRequest = async () => {
+  copyToClipboard(await generateSnippet())
+}
+
+function showItemInClient() {
+  const item = generateRequest(
+    props.operation,
+    parameterMap.value,
+    props.server,
+  )
+  setActiveRequest(item)
+  toggleApiClient()
+}
+
+// Store selected languages in LocalStorage
+const localStorageKey = 'preferredLanguage'
+const selectLanguage = (language: TargetId) => {
+  setItem('preferredLanguage', language)
+  localStorage.setItem(localStorageKey, language)
+}
+
+const availableLanguages = computed(() => {
+  return [
+    ...availableTargets().filter((target) => target.key !== 'http'),
+    { key: 'axios', title: 'JavaScript (Axios)' },
+    { key: 'laravel', title: 'PHP (Laravel)' },
+  ].sort((a, b) => a.title.localeCompare(b.title))
+})
+</script>
+<template>
+  <Card class="dark-mode">
+    <CardHeader muted>
+      <span :class="`request-method request-method--${operation.httpVerb}`">
+        {{ operation.httpVerb }}
+      </span>
+      <span class="request-path">{{ operation.path }}</span>
+
+      <template #actions>
+        <div class="language-select">
+          <span>{{
+            getLanguageTitleByKey(templateState.preferredLanguage)
+          }}</span>
+          <select
+            class="language-select"
+            :value="templateState.preferredLanguage"
+            @input="event => selectLanguage((event.target as HTMLSelectElement).value as TargetId)">
+            <option
+              v-for="lang in availableLanguages"
+              :key="lang.key"
+              :value="lang.key">
+              {{ lang.title }}
+            </option>
+          </select>
+        </div>
+
+        <button
+          class="copy-button"
+          type="button"
+          @click="copyExampleRequest">
+          <Icon
+            src="solid/interface-copy-clipboard"
+            width="10px" />
+        </button>
+      </template>
+    </CardHeader>
+    <CardContent
+      borderless
+      frameless>
+      <div ref="codeMirrorRef" />
+    </CardContent>
+    <CardFooter muted>
+      <button
+        class="show-api-client-button"
+        type="button"
+        @click="showItemInClient">
+        <Icon src="solid/mail-send-email-paper-airplane" />
+        Test {{ operation.httpVerb }} Request in Client
+      </button>
+    </CardFooter>
+  </Card>
+</template>
+<style scoped>
+.request-method--post {
+  color: var(--scalar-api-reference-theme-post-color);
+}
+.request-method--patch {
+  color: var(--scalar-api-reference-theme-patch-color);
+}
+.request-method--get {
+  color: var(--scalar-api-reference-theme-get-color);
+}
+.request-method--delete {
+  color: var(--scalar-api-reference-theme-delete-color);
+}
+.request-method--put {
+  color: var(--scalar-api-reference-theme-put-color);
+}
+.request-path {
+  margin-left: 6px;
+  color: var(--scalar-api-reference-theme-color-2);
+  white-space: nowrap;
+  overflow: hidden;
+  cursor: default;
+  text-overflow: ellipsis;
+  text-transform: none !important;
+}
+
+.language-select {
+  position: relative;
+  padding-right: 9px;
+  border-right: 1px solid var(--scalar-api-reference-theme-border-color);
+}
+.language-select select {
+  border: none;
+  outline: none;
+  cursor: pointer;
+  background: var(--scalar-api-reference-theme-background-3);
+  box-shadow: -2px 0 0 0 var(--scalar-api-reference-theme-background-3);
+  z-index: 2;
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  opacity: 0;
+  appearance: none;
+}
+.language-select span {
+  font-size: 12px;
+  color: var(--scalar-api-reference-theme-color-3);
+  font-weight: var(--scalar-api-reference-theme-semibold);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.language-select span:after {
+  content: '';
+  width: 7px;
+  height: 7px;
+  transform: rotate(45deg) translate3d(-2px, -2px, 0);
+  display: block;
+  margin-left: 6px;
+  box-shadow: 1px 1px 0 currentColor;
+}
+.language-select span:hover {
+  background: var(--scalar-api-reference-theme-background-2);
+}
+
+.copy-button {
+  appearance: none;
+  -webkit-appearance: none;
+  outline: none;
+  background: transparent;
+  display: flex;
+  cursor: pointer;
+  color: var(--scalar-api-reference-theme-color-3);
+  margin-left: 6px;
+  border: none;
+  border-radius: 3px;
+  &:hover {
+    color: var(--scalar-api-reference-theme-color-1);
+  }
+  svg {
+    width: 13px;
+    height: 13px;
+  }
+}
+
+.show-api-client-button {
+  width: 100%;
+  display: block;
+  appearance: none;
+  outline: none;
+  border: none;
+  border-radius: var(--scalar-api-reference-theme-radius-lg);
+  height: 35px;
+  display: flex;
+  justify-content: center;
+  cursor: pointer;
+  align-items: center;
+  font-weight: var(--scalar-api-reference-theme-bold);
+  font-size: var(--scalar-api-reference-theme-micro);
+  text-transform: uppercase;
+  border: 1px solid currentColor;
+  background: var(--scalar-api-reference-theme-button-1);
+  color: var(--scalar-api-reference-theme-button-1-color);
+}
+.show-api-client-button:hover {
+  background: var(--scalar-api-reference-theme-button-1-hover);
+}
+.show-api-client-button svg {
+  height: 12px;
+  width: auto;
+  margin-right: 6px;
+}
+
+.request-method {
+  font-family: var(--scalar-api-reference-font-mono);
+}
+.request-path {
+  font-family: var(--scalar-api-reference-font-mono);
+}
+</style>

package/src/components/Content/ReferenceEndpoint/ExampleResponseTab.vue

@@ -0,0 +1,22 @@
+<script lang="ts" setup>
+import { httpStatusCodes } from '@scalar/api-client'
+import { useTooltip } from '@scalar/use-tooltip'
+import { computed } from 'vue'
+
+const props = defineProps<{ title: string }>()
+
+const statusText = computed(() => {
+  return httpStatusCodes[props.title]?.name ?? null
+})
+
+const tooltipRef = useTooltip({
+  content: statusText.value,
+})
+</script>
+<template>
+  <span
+    ref="tooltipRef"
+    class="codemenu-item-key">
+    {{ title }}
+  </span>
+</template>

package/src/components/Content/ReferenceEndpoint/ExampleResponses.vue

@@ -0,0 +1,134 @@
+<script lang="ts" setup>
+import { json } from '@codemirror/lang-json'
+import { useClipboard } from '@scalar/use-clipboard'
+import { useCodeMirror } from '@scalar/use-codemirror'
+import { EditorView } from 'codemirror'
+import { computed, ref, watch } from 'vue'
+
+import type { TransformedOperation } from '../../../types'
+import {
+  Card,
+  CardContent,
+  CardFooter,
+  CardTab,
+  CardTabHeader,
+} from '../../Card'
+import { Icon } from '../../Icon'
+
+const props = defineProps<{ operation: TransformedOperation }>()
+
+const { copyToClipboard } = useClipboard()
+
+// Bring the status codes in the right order.
+const orderedStatusCodes = computed(() => {
+  return Object.keys(props.operation.information.responses).sort((x) => {
+    if (x === 'default') {
+      return -1
+    }
+
+    return 0
+  })
+})
+
+// Keep track of the current selected tab
+const selectedResponseIndex = ref<number>(0)
+
+// Return the whole response object
+const currentResponse = computed(() => {
+  const currentStatusCode =
+    orderedStatusCodes.value[selectedResponseIndex.value]
+
+  return props.operation.responses[currentStatusCode]
+})
+
+const currentResponseJsonBody = computed(() => {
+  return currentResponse.value?.content?.['application/json']?.body
+})
+
+const { codeMirrorRef, setCodeMirrorContent } = useCodeMirror({
+  content: currentResponseJsonBody.value,
+  extensions: [json(), EditorView.editable.of(false)],
+})
+
+const changeTab = (index: number) => {
+  selectedResponseIndex.value = index
+}
+
+watch(selectedResponseIndex, () => {
+  setCodeMirrorContent(currentResponseJsonBody.value ?? '')
+})
+</script>
+<template>
+  <Card>
+    <CardTabHeader
+      muted
+      @change="changeTab">
+      <CardTab
+        v-for="statusCode in orderedStatusCodes"
+        :key="statusCode">
+        {{ statusCode }}
+      </CardTab>
+
+      <template #actions>
+        <button
+          v-if="currentResponseJsonBody"
+          class="code-copy"
+          type="button"
+          @click="() => copyToClipboard(currentResponseJsonBody)">
+          <Icon
+            src="solid/interface-copy-clipboard"
+            width="10px" />
+        </button>
+      </template>
+    </CardTabHeader>
+    <CardContent muted>
+      <div
+        v-show="currentResponseJsonBody"
+        ref="codeMirrorRef" />
+      <div
+        v-if="!currentResponseJsonBody"
+        class="scalar-api-reference__empty-state">
+        No Body
+      </div>
+    </CardContent>
+    <CardFooter
+      v-if="currentResponse.description"
+      muted>
+      <div class="description">
+        {{ currentResponse.description }}
+      </div>
+    </CardFooter>
+  </Card>
+</template>
+
+<style scoped>
+.code-copy {
+  display: flex;
+  appearance: none;
+  -webkit-appearance: none;
+  outline: none;
+  background: transparent;
+  cursor: pointer;
+  color: var(--scalar-api-reference-theme-color-3);
+  border: none;
+}
+.code-copy:hover {
+  color: var(--scalar-api-reference-theme-color-1);
+}
+.code-copy svg {
+  width: 13px;
+  height: 13px;
+}
+.description {
+  font-weight: var(--scalar-api-reference-theme-semibold);
+  font-size: var(--scalar-api-reference-theme-mini);
+}
+.scalar-api-reference__empty-state {
+  border: 1px dashed var(--scalar-api-reference-theme-border-color);
+  width: 100%;
+  text-align: center;
+  font-size: var(--scalar-api-reference-theme-mini);
+  padding: 20px;
+  color: var(--scalar-api-reference-theme-color-2);
+}
+</style>

package/src/components/Content/ReferenceEndpoint/ParameterItem.vue

@@ -0,0 +1,26 @@
+<script setup lang="ts">
+import type { Parameters } from '../../../types'
+import MarkdownRenderer from '../MarkdownRenderer.vue'
+
+defineProps<{ parameter: Parameters }>()
+</script>
+<template>
+  <li>
+    <span class="parameter-name">{{ parameter.name }}</span>
+    <span
+      v-if="parameter.required !== undefined"
+      class="parameter-required"
+      :class="parameter.required ? 'marc_required' : ''">
+      {{ parameter.required ? 'required' : 'optional' }}
+    </span>
+    <span
+      v-if="parameter.schema?.type"
+      class="parameter-type">
+      {{ parameter.schema?.type }}
+    </span>
+    <MarkdownRenderer
+      v-if="parameter.description"
+      class="parameter-description"
+      :value="parameter.description" />
+  </li>
+</template>

package/src/components/Content/ReferenceEndpoint/Parameters.vue

@@ -0,0 +1,23 @@
+<script setup lang="ts">
+import type { Parameters } from '../../../types'
+import ParameterItem from './ParameterItem.vue'
+
+defineProps<{ parameters?: Parameters[]; title: string }>()
+</script>
+<template>
+  <div
+    v-if="parameters?.length"
+    class="parameters-container">
+    <div class="endpoint-title">
+      <h5 class="title">
+        {{ title }}
+      </h5>
+    </div>
+    <ul class="parameter">
+      <ParameterItem
+        v-for="item in parameters"
+        :key="item.name"
+        :parameter="item" />
+    </ul>
+  </div>
+</template>

package/src/components/Content/ReferenceEndpoint/ReferenceEndpoint.vue

@@ -0,0 +1,29 @@
+<script setup lang="ts">
+import type { Server, Tag, TransformedOperation } from '../../../types'
+import Copy from './Copy.vue'
+import ExampleRequest from './ExampleRequest.vue'
+import ExampleResponses from './ExampleResponses.vue'
+
+defineProps<{
+  operation: TransformedOperation
+  server: Server
+  parentTag: Tag
+}>()
+</script>
+<template>
+  <div
+    :id="`endpoint/${operation.operationId}`"
+    class="reference-container">
+    <Copy
+      :operation="operation"
+      :parentTag="parentTag" />
+    <div class="example">
+      <ExampleRequest
+        :operation="operation"
+        :server="server" />
+    </div>
+    <div class="example">
+      <ExampleResponses :operation="operation" />
+    </div>
+  </div>
+</template>