@scalar/api-reference 0.2.0 → 0.3.0

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

@@ -0,0 +1,317 @@
+<script setup lang="ts">
+import {
+  CodeMirror,
+  generateRequest,
+  useApiClientRequestStore,
+  useApiClientStore,
+  useOperation,
+} from '@scalar/api-client'
+import { useClipboard } from '@scalar/use-clipboard'
+import {
+  HTTPSnippet,
+  type HarRequest,
+  type TargetId,
+  availableTargets,
+} from 'httpsnippet-lite'
+import { computed, onMounted, ref, 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 CodeMirrorValue = ref<string>('')
+
+const { copyToClipboard } = useClipboard()
+
+const { setActiveRequest } = useApiClientRequestStore()
+
+const { toggleApiClient } = useApiClientStore()
+
+const {
+  state: templateState,
+  getLanguageTitleByKey,
+  setItem,
+} = useTemplateStore()
+
+const CodeMirrorLanguages = computed(() => {
+  return [templateState.preferredLanguage]
+})
+
+const { parameterMap } = useOperation(props)
+
+async function generateSnippet() {
+  let path = props.operation.path
+
+  // Replace all variables of the format {something} with the uppercase variable name without the brackets
+  const pathVariables = path.match(/{(.*?)}/g)
+
+  if (pathVariables) {
+    pathVariables.forEach((variable) => {
+      const variableName = variable.replace(/{|}/g, '')
+      path = path.replace(variable, variableName.toUpperCase())
+    })
+  }
+
+  if (templateState.preferredLanguage === 'axios') {
+    return generateAxiosCodeFromRequest({
+      method: props.operation.httpVerb.toUpperCase(),
+      url: `${props.server.url}${path}`,
+    })
+  } else if (templateState.preferredLanguage === 'laravel') {
+    return generateLaravelCodeFromRequest({
+      method: props.operation.httpVerb.toUpperCase(),
+      url: `${props.server.url}${path}`,
+    })
+  }
+
+  try {
+    const snippet = new HTTPSnippet({
+      method: props.operation.httpVerb.toUpperCase(),
+      url: `${props.server.url}${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}${path}`,
+    } as HarRequest)
+    const output = (await snippet.convert(
+      templateState.preferredLanguage as TargetId,
+    )) as string
+
+    return output
+  }
+}
+
+onMounted(async () => {
+  const initialSnippet = await generateSnippet()
+  CodeMirrorValue.value = initialSnippet
+  watch(
+    () => templateState.preferredLanguage,
+    async () => {
+      const output = await generateSnippet()
+      CodeMirrorValue.value = output
+    },
+  )
+})
+
+const copyExampleRequest = async () => {
+  copyToClipboard(CodeMirrorValue.value)
+}
+
+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>
+      <!-- @vue-ignore -->
+      <CodeMirror
+        :content="CodeMirrorValue"
+        :languages="CodeMirrorLanguages"
+        :lineNumbers="true"
+        :readOnly="true" />
+    </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(--theme-post-color);
+}
+.request-method--patch {
+  color: var(--theme-patch-color);
+}
+.request-method--get {
+  color: var(--theme-get-color);
+}
+.request-method--delete {
+  color: var(--theme-delete-color);
+}
+.request-method--put {
+  color: var(--theme-put-color);
+}
+.request-path {
+  margin-left: 6px;
+  color: var(--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(--theme-border-color);
+}
+.language-select select {
+  border: none;
+  outline: none;
+  cursor: pointer;
+  background: var(--theme-background-3);
+  box-shadow: -2px 0 0 0 var(--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(--theme-color-3);
+  font-weight: var(--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(--theme-background-2);
+}
+
+.copy-button {
+  appearance: none;
+  -webkit-appearance: none;
+  outline: none;
+  background: transparent;
+  display: flex;
+  cursor: pointer;
+  color: var(--theme-color-3);
+  margin-left: 6px;
+  border: none;
+  border-radius: 3px;
+}
+
+.copy-button:hover {
+  color: var(--theme-color-1);
+}
+
+.copy-button svg {
+  width: 13px;
+  height: 13px;
+}
+
+.show-api-client-button {
+  width: 100%;
+  display: block;
+  appearance: none;
+  outline: none;
+  border: none;
+  border-radius: var(--theme-radius-lg);
+  height: 35px;
+  display: flex;
+  justify-content: center;
+  cursor: pointer;
+  align-items: center;
+  font-weight: var(--theme-bold);
+  font-size: var(--theme-micro);
+  text-transform: uppercase;
+  border: 1px solid currentColor;
+  background: var(--theme-button-1);
+  color: var(--theme-button-1-color);
+}
+.show-api-client-button:hover {
+  background: var(--theme-button-1-hover);
+}
+.show-api-client-button svg {
+  height: 12px;
+  width: auto;
+  margin-right: 6px;
+}
+
+.request-method {
+  font-family: var(--theme-font-code);
+}
+.request-path {
+  font-family: var(--theme-font-code);
+}
+</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,168 @@
+<script lang="ts" setup>
+import { CodeMirror, type HttpHeader, httpHeaders } from '@scalar/api-client'
+import { useClipboard } from '@scalar/use-clipboard'
+import { computed, ref } from 'vue'
+
+import type { TransformedOperation } from '../../../types'
+import {
+  Card,
+  CardContent,
+  CardFooter,
+  CardTab,
+  CardTabHeader,
+} from '../../Card'
+import { Icon } from '../../Icon'
+import {
+  SimpleCell,
+  SimpleHeader,
+  SimpleRow,
+  SimpleTable,
+} from '../../SimpleTable'
+
+const props = defineProps<{ operation: TransformedOperation }>()
+
+const { copyToClipboard } = useClipboard()
+
+// Bring the status codes in the right order.
+const orderedStatusCodes = computed(() => {
+  return Object.keys(props?.operation?.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 changeTab = (index: number) => {
+  selectedResponseIndex.value = index
+}
+
+const getDocumentationUrlForHttpHeader = (headerName: string) => {
+  return httpHeaders.find((header: HttpHeader) => {
+    return header.name.toLowerCase() === headerName.toLowerCase()
+  })?.url
+}
+
+// Make the first letter and all letters after a - uppercase
+const formatHeaderName = (headerName: string) => {
+  return headerName
+    .split('-')
+    .map((word) => {
+      return word.charAt(0).toUpperCase() + word.slice(1)
+    })
+    .join('-')
+}
+</script>
+<template>
+  <Card v-if="orderedStatusCodes.length">
+    <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
+      v-if="currentResponse.headers"
+      muted>
+      <SimpleTable>
+        <SimpleRow>
+          <SimpleHeader>Header</SimpleHeader>
+          <SimpleHeader>Description</SimpleHeader>
+        </SimpleRow>
+        <SimpleRow
+          v-for="(data, header) in currentResponse.headers"
+          :key="header">
+          <SimpleCell
+            :href="getDocumentationUrlForHttpHeader(header)"
+            :strong="true"
+            :wrap="false">
+            {{ formatHeaderName(header) }}
+          </SimpleCell>
+          <SimpleCell>{{ data.description }}</SimpleCell>
+        </SimpleRow>
+      </SimpleTable>
+    </CardContent>
+    <CardContent muted>
+      <CodeMirror
+        v-show="currentResponseJsonBody"
+        :content="currentResponseJsonBody"
+        :languages="['json']"
+        readOnly />
+      <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(--theme-color-3);
+  border: none;
+}
+.code-copy:hover {
+  color: var(--theme-color-1);
+}
+.code-copy svg {
+  width: 13px;
+  height: 13px;
+}
+.description {
+  font-weight: var(--theme-semibold);
+  font-size: var(--theme-micro);
+}
+.scalar-api-reference__empty-state {
+  border: 1px dashed var(--theme-border-color);
+  width: 100%;
+  text-align: center;
+  font-size: var(--theme-micro);
+  padding: 20px;
+  color: var(--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" />
+      <ExampleResponses
+        :operation="operation"
+        style="margin-top: 12px" />
+    </div>
+  </div>
+</template>

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

@@ -0,0 +1,125 @@
+<script setup lang="ts">
+import type { RequestBody } from '../../../types'
+import RequestBodyProperties from './RequestBodyProperties.vue'
+
+defineProps<{ requestBody?: RequestBody }>()
+</script>
+<template>
+  <div
+    v-if="requestBody && requestBody.content['application/json']"
+    class="body-container">
+    <div class="endpoint-title">
+      <h5 class="title">Body</h5>
+    </div>
+    <ul
+      v-if="requestBody.content['application/json']"
+      class="parameter">
+      <RequestBodyProperties
+        :contentProperties="
+          requestBody.content['application/json'].schema.properties || {}
+        "
+        :required="
+          requestBody.content['application/json'].schema.required || []
+        " />
+    </ul>
+  </div>
+</template>
+
+<style>
+.parameter p {
+  margin-top: 6px;
+}
+.parameter .parameter-child {
+  border: 1px solid var(--theme-border-color);
+  border-radius: 20px;
+  margin-top: 12px;
+  width: fit-content;
+}
+.parameter .parameter {
+  border: none !important;
+}
+.parameter-child-trigger {
+  padding: 6px 12px;
+  cursor: pointer;
+  font-weight: 500;
+  color: var(--theme-color-3);
+  font-size: var(--theme-micro);
+  display: flex;
+  align-items: center;
+  user-select: none;
+}
+.parameter-child-trigger:has(+ .parameter li:first-of-type:last-of-type) {
+  display: none;
+}
+.parameter-child-trigger:hover {
+  color: var(--theme-color-1);
+}
+.parameter-child-trigger > span:before {
+  content: 'Show ';
+}
+.parameter-child__open > .parameter-child-trigger span:before {
+  content: 'Hide ';
+}
+.parameter-child-trigger svg {
+  height: 10px;
+  width: 10px;
+  margin-right: 6px;
+}
+.parameter-child__open .parameter-child-trigger svg {
+  transform: rotate(45deg);
+}
+.parameter .parameter li:first-of-type {
+  border-top: none;
+}
+.parameter .parameter li {
+  padding: 12px;
+}
+.parameter-child__open > .parameter {
+  display: block;
+}
+.parameter .parameter-child__open {
+  width: 100%;
+  border-radius: 6px;
+}
+.parameter .parameter-child__open > svg {
+  transform: rotate(45deg);
+}
+.parameter-child__open > .parameter-child-trigger {
+  border-bottom: 1px solid var(--theme-border-color);
+}
+
+.parameter {
+  list-style: none;
+  font-size: var(--theme-small);
+}
+.parameter li {
+  border-top: 1px solid var(--theme-border-color);
+  padding: 12px 0;
+}
+.parameter-name {
+  font-weight: 500;
+  margin-right: 6px;
+  font-family: var(--theme-font-code);
+  font-size: 13px;
+  color: var(--theme-color-1);
+}
+.parameter-type,
+.parameter-required {
+  color: var(--theme-color-3);
+  font-weight: var(--theme-semibold);
+  margin-right: 6px;
+  position: relative;
+}
+.marc_required {
+  text-transform: uppercase;
+  font-size: 11px;
+  font-weight: var(--theme-bold);
+  color: #ffb040;
+}
+.parameter-options {
+  position: relative;
+}
+.copy .parameter-description:empty {
+  display: none;
+}
+</style>