@scalar/api-reference 0.2.0 → 0.3.0

package/src/helpers/transformToJson.ts

@@ -0,0 +1,22 @@
+import yaml from 'js-yaml'
+
+/**
+ * This helper is used to transform the content of the swagger file to JSON, even it was YAML.
+ */
+export const transformToJson = (value: string) => {
+  try {
+    // JSON
+    JSON.parse(value)
+
+    return value
+  } catch {
+    try {
+      // Yaml to JSON
+      const doc = yaml.load(value)
+      return JSON.stringify(doc)
+    } catch {
+      // Invalid
+      return value
+    }
+  }
+}

package/src/hooks/useRefOnMount.ts

@@ -0,0 +1,12 @@
+import { type Ref, onMounted, ref } from 'vue'
+
+// Set a ref value on mount when needed to access properties that are not SSR friendly
+export function useRefOnMount<T>(setter: () => T) {
+  const value: Ref<T | null> = ref(null)
+
+  onMounted(() => {
+    value.value = setter()
+  })
+
+  return value
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+import '../../theme/scrollbar.css'
+
+export {
+  default as ApiClientModal,
+  useApiClientStore,
+} from './components/ApiClientModal.vue'
+export { default as ApiReference } from './components/ApiReference.vue'
+export { default as Sidebar } from './components/Sidebar.vue'
+export { default as RenderedReference } from './components/Content/Content.vue'
+
+export * from './types'

package/src/standalone.ts

@@ -0,0 +1,28 @@
+import { createApp } from 'vue'
+
+import '../../theme/scrollbar.css'
+import ApiReference from './components/ApiReference.vue'
+
+const specElement = document.querySelector('[data-spec]')
+const specUrlElement = document.querySelector('[data-spec-url]')
+
+if (!specUrlElement && !specElement) {
+  console.error(
+    'Couldn’t find a [data-spec] or [data-spec-url] element. Try adding it like this: %c<div data-spec-url="https://petstore.swagger.io/v2/swagger.json" />',
+    'font-family: monospace;',
+  )
+} else {
+  const properties = specElement
+    ? {
+        spec: specElement.getAttribute('data-spec'),
+      }
+    : {
+        specUrl: specUrlElement?.getAttribute('data-spec-url') ?? '',
+      }
+
+  document.querySelector('body')?.classList.add('light-mode')
+
+  const container = specElement ? '[data-spec]' : '[data-spec-url]'
+
+  createApp(ApiReference, properties).mount(container)
+}

package/src/stores/template.ts

@@ -0,0 +1,66 @@
+/**
+ * TODO: This is a copy of projects/web/src/stores/template.ts
+ */
+import { type TargetId, availableTargets } from 'httpsnippet-lite'
+import { reactive, readonly } from 'vue'
+
+import { objectMerge } from '../helpers/objectMerge'
+import { setItemFactory, toggleItemFactory } from './utility'
+
+export enum NavState {
+  Guide = 'Guide',
+  Reference = 'Reference',
+}
+
+type TemplateState = {
+  isDark: boolean
+  showSideBar: boolean
+  showSearch: boolean
+  activeNavState: NavState
+  collapsedSidebarItems: Partial<Record<string, boolean>>
+  preferredLanguage: TargetId | 'axios' | 'laravel'
+}
+
+const defaultTemplateState = (): TemplateState => ({
+  isDark: false,
+  showSearch: false,
+  showSideBar: true,
+  activeNavState: NavState.Guide,
+  collapsedSidebarItems: {},
+  preferredLanguage: 'shell',
+})
+
+const state = reactive<TemplateState>(defaultTemplateState())
+
+function resetState() {
+  objectMerge(state, defaultTemplateState())
+}
+
+function toggleCollapsedSidebarItem(key: string) {
+  state.collapsedSidebarItems[key] = !state.collapsedSidebarItems[key] ?? true
+}
+
+function setCollapsedSidebarItem(key: string, value: boolean) {
+  state.collapsedSidebarItems[key] = value
+}
+
+// getLanguageTitleByKey('javascript') => 'JavaScript'
+function getLanguageTitleByKey(language: TargetId | 'axios' | 'laravel') {
+  if (language === 'axios') {
+    return 'JavaScript (Axios)'
+  } else if (language === 'laravel') {
+    return 'PHP (Laravel)'
+  }
+
+  return availableTargets().find((target) => language === target.key)?.title
+}
+
+export const useTemplateStore = () => ({
+  state: readonly(state),
+  resetState,
+  setItem: setItemFactory(state),
+  toggleItem: toggleItemFactory(state),
+  toggleCollapsedSidebarItem,
+  setCollapsedSidebarItem,
+  getLanguageTitleByKey,
+})

package/src/stores/utility.ts

@@ -0,0 +1,23 @@
+/**
+ * TODO: This is a copy of projects/web/src/stores/utility.ts
+ */
+export type KeyOfType<T, V> = keyof {
+  [P in keyof T as T[P] extends V ? P : never]: any
+}
+
+/** Generic set item for a given store state */
+export function setItemFactory<State extends object>(state: State) {
+  return function setItem<K extends keyof State>(key: K, value: State[K]) {
+    state[key] = value
+  }
+}
+
+export function toggleItemFactory<State extends object>(state: State) {
+  return function toggleItem(key: KeyOfType<State, boolean>) {
+    if (typeof state[key] === 'boolean') {
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      state[key] = !state[key]
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,154 @@
+export type ReferenceProps = {
+  documentName?: string
+  token?: string
+  username?: string
+  hocusPocusUrl?: string
+  isEditable?: boolean
+  showSidebar?: boolean
+  footerBelowSidebar?: boolean
+  spec?: string
+  specUrl?: string
+}
+
+export type Security = {
+  api_key?: any[]
+  petstore_auth?: string[]
+}
+export type Schema = {
+  format: string
+  type: string
+}
+
+export type Parameters = {
+  description?: string
+  in?: string
+  name: string
+  required?: boolean
+  schema?: Schema
+}
+
+export type Response = {
+  description: string
+  content: any
+}
+
+export type Information = {
+  description: string
+  operationId: string
+  parameters: Parameters[]
+  responses: Record<string, Response>
+  security: Security[]
+  requestBody: RequestBody
+  summary: string
+  tags: string[]
+}
+
+export type Operation = {
+  httpVerb: string
+  path: string
+  operationId: string
+  name: string
+  description: string
+  information: Information
+}
+
+export type TransformedOperation = Operation & {
+  responses: Record<
+    string,
+    Response & {
+      headers: Record<
+        string,
+        {
+          description: string
+          schema: {
+            type: string
+            format?: string
+          }
+        }
+      >
+    }
+  >
+}
+
+export type Tag = {
+  name: string
+  description: string
+  operations: TransformedOperation[]
+}
+export type Parameter = {
+  name: string
+  required: boolean
+  displayType: string
+  description: string
+}
+
+export type ContentProperties = {
+  [key: string]: {
+    type: string
+    format: string
+    example: string
+    required: string[]
+    description?: string
+    properties?: ContentProperties
+  }
+}
+
+export type ContentSchema = {
+  schema: {
+    type: string
+    required: string[]
+    properties: ContentProperties
+  }
+}
+
+export type ContentType =
+  | 'application/json'
+  | 'application/xml'
+  | 'text/plain'
+  | 'text/html'
+  | 'application/x-www-form-urlencoded'
+  | 'multipart/form-data'
+
+export type Content = {
+  [key in ContentType]: ContentSchema
+}
+
+export type RequestBody = {
+  description: string
+  content: Content
+  required: boolean
+}
+
+export type Contact = {
+  email: string
+}
+
+export type License = {
+  name: string
+  url: string
+}
+
+export type Info = {
+  title: string
+  description: string
+  termsOfService: string
+  contact: Contact
+  license: License
+  version: string
+}
+
+export type ExternalDocs = {
+  description: string
+  url: string
+}
+
+export type Server = {
+  url: string
+}
+
+export type Spec = {
+  tags: Tag[]
+  info: Info
+  externalDocs: ExternalDocs
+  servers: Server[]
+}