feat(api-reference): `RequestExample` embed

[hanspagel]

This PR adds a standalone RequestExample Vue component.

This and all future components will need to dereference the OpenAPI document. We probably don’t want to do this in every embed, so I’ve also embed an OpenApiDocument which does the data wrangling and can then be used by one or multiple instances of the ExampleRequest component.

In order to bring this to life, the components need to be really encapsulated, so I’ve had to move some code. I think that’s a great way to improve our code quality. :)

Supports the relevant parts of the configuration: proxy, spec, hiddenClients, defaultHttpClient, baseServerUrl, servers, authentication.

Usage

Note: While this PR adds the embeds, it doesn’t expose them yet. Let’s polish them a little bite more before making them available to everyone. :)

<script setup>
// TODO: The package doesn’t have this entrypoint yet.
import { OpenApiDocument, ExampleRequest } from '@scalar/api-reference/embeds'
</script>

<template>
  <OpenApiDocument
    v-slot="{ configuration, parsedSpec }"
    :configuration="{
      proxy: 'https://proxy.scalar.com',
      spec: {
        url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.json',
      }
    }">
  
    <ExampleRequest
      :configuration="configuration"
      :operation="parsedSpec.tags?.[1]?.operations?.[1]"
      :parsedSpec="parsedSpec" />
  
  </OpenApiDocument>
</template>

Playground

cd packages/api-reference
pnpm playground:embed

Preview

[changeset-bot[bot]]

🦋 Changeset detected

Latest commit: 65233d20e1d2402617031473b644d0b2284148d5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 10 packages

Name	Type
@scalar/api-reference	Patch
@scalar/api-reference-editor	Patch
@scalar/api-reference-react	Patch
@scalar/cli	Patch
@scalar/express-api-reference	Patch
@scalar/fastify-api-reference	Patch
@scalar/nestjs-api-reference	Patch
@scalar/nuxt	Patch
@scalar/play-button	Patch
@scalar/docusaurus	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[relativeci[bot]]

#4149 Bundle Size — 2.09MiB (~+0.01%).

65233d2(current) vs b9afc73 main#4145(baseline)

[!WARNING] Bundle contains 4 duplicate packages – View duplicate packages

Bundle metrics   2 changes 1 regression

	Current #4149	Baseline #4145
Initial JS	2.09MiB(~+0.01%)	2.09MiB
Initial CSS	0B	0B
Cache Invalidation	100%	0%
Chunks	1	1
Assets	1	1
Modules	1236	1236
Duplicate Modules	0	0
Duplicate Code	0%	0%
Packages	169	169
Duplicate Packages	4	4

Bundle size by type   1 change 1 regression

	Current #4149	Baseline #4145
JS	2.09MiB (~+0.01%)	2.09MiB

Bundle analysis report Branch feat/embeds Project dashboard

---

^{Generated by RelativeCI Documentation Report issue}

[github-actions[bot]]

Cloudflare Preview for the API Client

https://066edb6a.client-980.pages.dev

[geoffgscott]

@hanspagel I think the approach around OpenApiDocument needs to be discussed a bit more. Looking at this the plan looks to be using it in third party consumers to provision specs for different types of embedded components.

I think we can do this better with a hook that exposes both the Vue reactive objects and an event based system that would be easier to interface with in other applications.

// Usage anywhere in the app. 
const { configuration, parsedSpec, addSpec  } = useOASDocument({
  key: 'some-spec-id',
  /** Event based interface for non-vue frameworks. */ 
  onSpecChange: (spec) => console.log(spec),
})

// Function used to add a spec to the app using a namespaced key
// This allows a spec to be uploaded/parsed once and referenced everywhere using the same key
addSpec({
  key: 'some-spec-id',
    ...baseConfig,
})

With your above point about tidying up the code by keeping code encapsulated I think this could help a lot with writing broader parts of the reference codebase as we can just provide a key to components and they can call useOASDocument() internally to get the data they need.

[hanspagel]

True and I fully agree. It was just slightly easier/faster to move the code from a component to another component and I wanted it to be hidden, but merged before I’m OOO.

I just rebased the PR and would love to get this in (still hidden) and work on a new PR with a better approach to expose this new functionally. Fine for everyone?

[github-actions[bot]]

Preview deployed to https://807dca5b-24df-451a-95e6-8f2348776371--scalar-deploy-preview.netlify.app

[hanspagel]

Cool! I’ll merge this and take over the responsibility to further improve the implementation according to @geoffgscott’s feedback. 🤝