@kirchdev/duxt 0.1.0

package/app/components/DuxtOpenApiMedia.vue

@@ -0,0 +1,108 @@
+<script setup lang="ts">
+import type { DuxtOpenApiMediaType } from '../../openapi-model';
+
+/**
+ * One body, in each media type the document offers it in.
+ *
+ * The media type is a tab rather than a heading: `application/json` and
+ * `multipart/form-data` are two spellings of ONE body, and stacking them reads
+ * as two bodies a request would carry both of.
+ */
+const props = defineProps<{
+  content?: DuxtOpenApiMediaType[];
+  /**
+   * Which way this body travels, and therefore which fields it can hold.
+   *
+   * Required rather than defaulted: this component draws the request body AND
+   * every response, and a default would have to be wrong for one of them. The
+   * only way a caller can forget is by not compiling.
+   */
+  direction: DuxtOpenApiDirection;
+}>();
+
+const types = computed(() => props.content ?? []);
+const current = ref(0);
+
+const media = computed(() => types.value[current.value] ?? types.value[0]);
+
+/** The examples the document wrote, and — where it wrote none — a derived one. */
+const examples = computed(() => {
+  const written = media.value?.examples ?? [];
+  if (written.length) return written;
+
+  const derived = openApiExampleValue(media.value?.schema, props.direction);
+
+  return derived === null ? [] : [{ name: 'example', value: derived }];
+});
+</script>
+
+<template>
+  <div v-if="types.length" class="min-w-0">
+    <div v-if="types.length > 1" class="mb-3 flex flex-wrap gap-1.5">
+      <button
+        v-for="(entry, index) in types"
+        :key="entry.type"
+        type="button"
+        class="rounded-md px-2 py-1 font-mono text-xs transition-colors"
+        :class="
+          index === current
+            ? 'bg-muted text-foreground'
+            : 'text-muted-foreground hover:text-foreground'
+        "
+        :aria-pressed="index === current"
+        @click="current = index"
+      >
+        {{ entry.type }}
+      </button>
+    </div>
+
+    <p v-else class="mb-2 font-mono text-xs text-muted-foreground">
+      {{ media?.type }}
+    </p>
+
+    <DuxtOpenApiSchema
+      v-if="media?.schema"
+      :schema="media.schema"
+      :direction="direction"
+    />
+
+    <div v-for="example in examples" :key="example.name" class="mt-3">
+      <p v-if="example.summary" class="mb-1 text-xs text-muted-foreground">
+        {{ example.summary }}
+      </p>
+
+      <!-- An external example is a URL the document points at; showing the URL
+           is the whole of what this build can honestly show. -->
+      <p
+        v-if="example.externalValue"
+        class="font-mono text-xs break-all text-muted-foreground"
+      >
+        {{ example.externalValue }}
+      </p>
+
+      <DuxtCodeBlock
+        v-else-if="example.value !== undefined"
+        :code="openApiJson(example.value)"
+        language="json"
+      />
+    </div>
+
+    <!-- How each part of a multipart body is encoded, which is otherwise the
+         one thing a reader cannot guess from the schema. -->
+    <dl
+      v-if="media?.encoding?.length"
+      class="mt-3 space-y-1 text-xs text-muted-foreground"
+    >
+      <div
+        v-for="entry in media.encoding"
+        :key="entry.property"
+        class="flex gap-2"
+      >
+        <dt class="font-mono">{{ entry.property }}</dt>
+        <dd v-if="entry.contentType" class="font-mono">
+          {{ entry.contentType }}
+        </dd>
+      </div>
+    </dl>
+  </div>
+</template>

package/app/components/DuxtOpenApiMethod.vue

@@ -0,0 +1,59 @@
+<script setup lang="ts">
+/**
+ * An HTTP method, as the chip every reference draws it as.
+ *
+ * A `UiBadge` WITH A TONE, not a pill of its own. The shape, the border, the
+ * radius and the sizing are the badge's — the same object the rest of the site
+ * marks things with — and what this component adds is the one thing a badge
+ * cannot know: which colour a method has. It was its own `span` before, built
+ * out of the same parts by hand, and it drifted from them the moment the badge
+ * changed.
+ *
+ * The colour is not decoration: a reader scanning a list of thirty endpoints
+ * finds the destructive one by its colour long before reading the word.
+ *
+ * `success` and `destructive` are the palette's own tokens; the rest are
+ * Tailwind's ramp, exactly as `Callout.vue` uses it — the theme has no token
+ * for "amber" and inventing four would put four more pairs into a palette a
+ * consumer overrides. A tenth of the colour as surface and a fifth as border is
+ * the badge's own construction, so every method reads as one of its badges and
+ * every one of them clears the contrast floor in both themes.
+ */
+const props = defineProps<{ method: string; class?: string }>();
+
+const tones: Record<string, string> = {
+  get: 'border-sky-500/20 bg-sky-500/10 text-sky-700 dark:text-sky-400',
+  post: 'border-success/20 bg-success/10 text-success',
+  put: 'border-amber-500/20 bg-amber-500/10 text-amber-700 dark:text-amber-400',
+  patch:
+    'border-violet-500/20 bg-violet-500/10 text-violet-700 dark:text-violet-400',
+  delete: 'border-destructive/20 bg-destructive/10 text-destructive',
+  head: 'border-border bg-muted text-muted-foreground',
+  options: 'border-border bg-muted text-muted-foreground',
+  trace: 'border-border bg-muted text-muted-foreground'
+};
+
+const tone = computed(
+  () =>
+    tones[props.method.toLowerCase()] ??
+    'border-border bg-muted text-muted-foreground'
+);
+</script>
+
+<template>
+  <!-- `leading-none` and a fixed height rather than vertical padding around a
+       line box: an uppercase monospace face leaves more room under the caps
+       than over them, so the word sat visibly high in a padded chip. With no
+       leading of its own the text box is the glyphs, and centring is exact.
+       Callers still set the width, which is what lines a column of methods up
+       beside a column of paths. -->
+  <UiBadge
+    :class="[
+      'h-5 px-1.5 font-mono text-[0.6875rem] leading-none font-semibold tracking-wide uppercase',
+      tone,
+      props.class
+    ]"
+  >
+    {{ method }}
+  </UiBadge>
+</template>

package/app/components/DuxtOpenApiParameters.vue

@@ -0,0 +1,114 @@
+<script setup lang="ts">
+import type { DuxtOpenApiParameter } from '../../openapi-model';
+
+/**
+ * The parameters an operation takes, grouped by where they go.
+ *
+ * GROUPED, not one flat table: `in` is the single most load-bearing field a
+ * parameter has — it decides whether the value goes in the URL, the query
+ * string, a header or a cookie — and a column carrying it is a column readers
+ * skim past. The heading says it once per group instead.
+ *
+ * A list rather than a `<table>` on purpose. A parameter is a name, a type, a
+ * sentence and a nested schema, and the schema does not fit in a cell: the
+ * table has to break out of itself for every object-shaped query parameter,
+ * which is most of them on a real API.
+ */
+const props = defineProps<{ parameters?: DuxtOpenApiParameter[] }>();
+
+const ORDER = ['path', 'query', 'header', 'cookie'] as const;
+
+const groups = computed(() =>
+  ORDER.map((where) => ({
+    where,
+    parameters: (props.parameters ?? []).filter(
+      (parameter) => parameter.in === where
+    )
+  })).filter((group) => group.parameters.length)
+);
+</script>
+
+<template>
+  <section v-if="groups.length" class="mt-8">
+    <h2 class="duxt-label">
+      {{ $t('duxt.openapi.parameters') }}
+    </h2>
+
+    <div v-for="group in groups" :key="group.where" class="mt-4">
+      <h3 class="text-xs font-medium text-foreground/80">
+        {{ $t(`duxt.openapi.in.${group.where}`) }}
+      </h3>
+
+      <ul class="mt-2 divide-y divide-border/60 border-t border-border/60">
+        <li
+          v-for="parameter in group.parameters"
+          :key="parameter.name"
+          class="py-3"
+        >
+          <DuxtOpenApiSchema
+            :schema="parameter.schema"
+            :name="parameter.name"
+            :required="parameter.required"
+            direction="request"
+          />
+
+          <p
+            v-if="parameter.description"
+            class="mt-1 text-sm text-muted-foreground"
+          >
+            {{ parameter.description }}
+          </p>
+
+          <p
+            v-if="parameter.deprecated"
+            class="mt-1 text-xs text-muted-foreground"
+          >
+            {{ $t('duxt.openapi.deprecated') }}
+          </p>
+
+          <!-- `style` and `explode` decide how an array or an object becomes
+               text in a URL, which is the difference between `?a=1&a=2` and
+               `?a=1,2`. The specification's own words, so they are shown as
+               written rather than translated into a paraphrase. -->
+          <div
+            v-if="
+              parameter.style ||
+              parameter.explode !== undefined ||
+              parameter.allowEmptyValue
+            "
+            class="mt-1.5 flex flex-wrap gap-1.5"
+          >
+            <span
+              v-if="parameter.style"
+              class="rounded bg-muted px-1.5 py-0.5 font-mono text-[0.6875rem] text-muted-foreground"
+            >
+              style={{ parameter.style }}
+            </span>
+            <span
+              v-if="parameter.explode !== undefined"
+              class="rounded bg-muted px-1.5 py-0.5 font-mono text-[0.6875rem] text-muted-foreground"
+            >
+              explode={{ parameter.explode }}
+            </span>
+            <span
+              v-if="parameter.allowEmptyValue"
+              class="rounded bg-muted px-1.5 py-0.5 font-mono text-[0.6875rem] text-muted-foreground"
+            >
+              allowEmptyValue
+            </span>
+          </div>
+
+          <!-- `content` instead of `schema` is how a document says a parameter
+               is serialised as a body — a JSON object in a query string. Rare,
+               and invisible if it is not drawn. -->
+          <div v-if="parameter.content?.length" class="mt-3">
+            <DuxtOpenApiMedia
+              :content="parameter.content"
+              direction="request"
+            />
+          </div>
+        </li>
+      </ul>
+    </div>
+  </section>
+</template>

package/app/components/DuxtOpenApiResponses.vue

@@ -0,0 +1,109 @@
+<script setup lang="ts">
+import type { DuxtOpenApiResponse } from '../../openapi-model';
+
+/**
+ * The responses an operation can send, in the order the parser put them.
+ *
+ * Every status expanded rather than one selected at a time. A reference is read
+ * to find out what the error shapes are, and a tab strip that hides four of
+ * five responses answers that question only for whoever already knew which tab
+ * to open.
+ */
+defineProps<{ responses?: DuxtOpenApiResponse[] }>();
+</script>
+
+<template>
+  <section v-if="responses?.length" class="mt-8">
+    <h2 class="duxt-label">
+      {{ $t('duxt.openapi.responses') }}
+    </h2>
+
+    <!-- A hairline between responses rather than a card around each: what
+         separates two of them is that one ends and the next begins, which is
+         what a rule says. The card said "one object" a third time on a page
+         that had already said it about the security and the parameters. -->
+    <div class="mt-3 divide-y divide-border/60 border-t border-border/60">
+      <div v-for="response in responses" :key="response.status" class="py-4">
+        <div class="flex flex-wrap items-center gap-3">
+          <UiBadge
+            :class="[
+              'h-5 px-1.5 font-mono text-[0.6875rem] leading-none font-semibold tabular-nums',
+              openApiStatusTone(response.status)
+            ]"
+          >
+            {{ response.status }}
+          </UiBadge>
+
+          <span v-if="response.description" class="text-sm">
+            {{ response.description }}
+          </span>
+        </div>
+
+        <div class="mt-3 space-y-4">
+          <div v-if="response.headers?.length">
+            <h3 class="mb-2 text-xs font-medium text-muted-foreground">
+              {{ $t('duxt.openapi.headers') }}
+            </h3>
+            <ul class="space-y-3">
+              <li v-for="header in response.headers" :key="header.name">
+                <DuxtOpenApiSchema
+                  :schema="header.schema"
+                  :name="header.name"
+                  :required="header.required"
+                  direction="response"
+                />
+                <p
+                  v-if="header.description"
+                  class="mt-1 text-sm text-muted-foreground"
+                >
+                  {{ header.description }}
+                </p>
+              </li>
+            </ul>
+          </div>
+
+          <DuxtOpenApiMedia
+            v-if="response.content?.length"
+            :content="response.content"
+            direction="response"
+          />
+
+          <p
+            v-else-if="!response.headers?.length"
+            class="text-sm text-muted-foreground"
+          >
+            {{ $t('duxt.openapi.noBody') }}
+          </p>
+
+          <!-- Links are the one part of the specification that says what a
+               reader can do NEXT with what came back, and the part every
+               renderer drops first. -->
+          <div v-if="response.links?.length">
+            <h3 class="mb-2 text-xs font-medium text-muted-foreground">
+              {{ $t('duxt.openapi.links') }}
+            </h3>
+            <ul class="space-y-2">
+              <li v-for="link in response.links" :key="link.name">
+                <div class="flex flex-wrap items-baseline gap-2">
+                  <code class="font-mono text-sm">{{ link.name }}</code>
+                  <span
+                    v-if="link.operationId ?? link.operationRef"
+                    class="font-mono text-xs text-muted-foreground"
+                  >
+                    {{ link.operationId ?? link.operationRef }}
+                  </span>
+                </div>
+                <p
+                  v-if="link.description"
+                  class="text-sm text-muted-foreground"
+                >
+                  {{ link.description }}
+                </p>
+              </li>
+            </ul>
+          </div>
+        </div>
+      </div>
+    </div>
+  </section>
+</template>