Create elegant OpenAPI spec documentation with Rapi Doc and Vitepress

I recently had to create a documentation page supporting OpenAPI spec documentation. What's an OpenAPI spec documentation? A page, either self-hosted or included in your API management platform, that allows users to check what endpoints, methods, webhooks, etc., are available based on OpenAPI JSON or YAML.

I needed to find a balance between needing as many customization options as possible and using ready-to-go tools for quick setup and deployment.

And I found

With the component ready, I needed a tool to write documentation that supported custom components.

So I chose

And my browser froze.

Woohoo, long live the infinite loop!

What happened? So, since rapi-doc is a web component, I need to explicitly tell Vue compiler to not parse it. To just leave it alone.

And inside my config.mts file I needed to add:

import { defineConfig } from 'vitepress'



// https://vitepress.dev/reference/site-config

export default defineConfig({

  ...

  vue: {

    template: {

      compilerOptions: {

        isCustomElement: (tag: string) => {

          return tag.indexOf('rapi-doc') >= 0;

        }

      }

    }

  },

})

We just need to check for custom elements and inform Vue "hey, this tag is off-limits".

So, we have it, it runs!

This error means that during build-time, Vite couldn't access a self property. This can also happen if you try to access browser API (e.g., window) from server (in Nuxt or any other SSR framework, for example).

So what we can do? We can import it dynamically in runtime!

Let's change our import from this:

<script setup>

import 'rapidoc';

</script>

To this:

<script setup>

import { onMounted } from 'vue';



onMounted(() => {

  import('rapidoc');

});

</script>

And now build should pass with no issues! Enjoy you API spec docs!

Bonus: Dark Mode

Vitepress comes with dark mode, working out-of-the-box. But how can we make our RapiDoc documentation reacting to mode changes?

We can use Vitepress core composable - useData. It contains isDark property with information if the darkmode is enabled or not.

So let's use it inside the script section in the SFC:

<script setup>

import { useData } from 'vitepress';

import { ref } from 'vue';



const data = useData();

const theme = ref(data.isDark.value ? 'dark' : 'light')

</script>

Now when we have a theme ref, we can pass it to the rapi-doc Web Component via attribute binding:

<template>

<div>

  <rapi-doc

      spec-url = "https://petstore.swagger.io/v2/swagger.json"

      render-style = "read"

      :theme="theme"

      style = "height:100vh; width:100%"

  > </rapi-doc>

</div>

</template>

We need to add one more thing for dark mode to work correctly - responding to theme change.

Let's add a watcher to our script section:

watch(data.isDark, (isDark) => {

  theme.value = isDark ? 'dark' : 'light';

})

And voila, you created API docs that react to theme changes!