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 Rapi Doc - a web component that can be embedded anywhere.
With the component ready, I needed a tool to write documentation that supported custom components.
So I chose Vitepress. And I had two tools that I wanted to merge. How did it go? Let's find out.
Running app in dev mode
I'll skip the story of Vitepress setup - you can find the instructions on their main page.
I also created a custom RapiDoc.vue component where I embedded my rapi-doc web component.
<script setup> import 'rapidoc' </script> <template> <div> <rapi-doc spec-url="https://petstore.swagger.io/v2/swagger.json" render-style="read" style="height:100vh; width:100%"> </rapi-doc> </div> </template> <style scoped> </style>
I also embedded this custom component in a api-docs.md page (yes, you can embed Vue Components in Markdown, I love Vitepress for it!) so I could see it in my Vitepress documentation.
--- sidebar: false layout: page --- <script setup> import RapiDoc from './components/RapiDoc.vue'; </script> <rapidoc></rapidoc>
I ran yarn docs:dev expecting everything to go smoothly (I followed the instructions from both documentations, so it should be fine, right?)...
And I got this:
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!
And then I tried to build it so I could set up deployment.
Building the app
I ran yarn docs:build command. And I immediately (wow, Vite, you're quick!) got this error:
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> <template> <div> <rapi-doc spec-url="https://petstore.swagger.io/v2/swagger.json" render-style="read" style="height:100vh; width:100%"> </rapi-doc> </div> </template> <style scoped> </style>
To this:
--- sidebar: false layout: page --- <script setup> import RapiDoc from './components/RapiDoc.vue'; </script> <rapidoc></rapidoc>
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:
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; } } } }, })
Now when we have a theme ref, we can pass it to the rapi-doc Web Component via attribute binding:
<script setup> import 'rapidoc'; </script>
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:
<script setup> import { onMounted } from 'vue'; onMounted(() => { import('rapidoc'); }); </script>
And voila, you created API docs that react to theme changes!
The above is the detailed content of Create elegant OpenAPI spec documentation with Rapi Doc and Vitepress. For more information, please follow other related articles on the PHP Chinese website!

Detailed explanation of JavaScript string replacement method and FAQ This article will explore two ways to replace string characters in JavaScript: internal JavaScript code and internal HTML for web pages. Replace string inside JavaScript code The most direct way is to use the replace() method: str = str.replace("find","replace"); This method replaces only the first match. To replace all matches, use a regular expression and add the global flag g: str = str.replace(/fi

Leverage jQuery for Effortless Web Page Layouts: 8 Essential Plugins jQuery simplifies web page layout significantly. This article highlights eight powerful jQuery plugins that streamline the process, particularly useful for manual website creation

So here you are, ready to learn all about this thing called AJAX. But, what exactly is it? The term AJAX refers to a loose grouping of technologies that are used to create dynamic, interactive web content. The term AJAX, originally coined by Jesse J

10 fun jQuery game plugins to make your website more attractive and enhance user stickiness! While Flash is still the best software for developing casual web games, jQuery can also create surprising effects, and while not comparable to pure action Flash games, in some cases you can also have unexpected fun in your browser. jQuery tic toe game The "Hello world" of game programming now has a jQuery version. Source code jQuery Crazy Word Composition Game This is a fill-in-the-blank game, and it can produce some weird results due to not knowing the context of the word. Source code jQuery mine sweeping game

Article discusses creating, publishing, and maintaining JavaScript libraries, focusing on planning, development, testing, documentation, and promotion strategies.

This tutorial demonstrates how to create a captivating parallax background effect using jQuery. We'll build a header banner with layered images that create a stunning visual depth. The updated plugin works with jQuery 1.6.4 and later. Download the

This tutorial demonstrates creating dynamic page boxes loaded via AJAX, enabling instant refresh without full page reloads. It leverages jQuery and JavaScript. Think of it as a custom Facebook-style content box loader. Key Concepts: AJAX and jQuery

This JavaScript library leverages the window.name property to manage session data without relying on cookies. It offers a robust solution for storing and retrieving session variables across browsers. The library provides three core methods: Session


Hot AI Tools

Undresser.AI Undress
AI-powered app for creating realistic nude photos

AI Clothes Remover
Online AI tool for removing clothes from photos.

Undress AI Tool
Undress images for free

Clothoff.io
AI clothes remover

AI Hentai Generator
Generate AI Hentai for free.

Hot Article

Hot Tools

VSCode Windows 64-bit Download
A free and powerful IDE editor launched by Microsoft

DVWA
Damn Vulnerable Web App (DVWA) is a PHP/MySQL web application that is very vulnerable. Its main goals are to be an aid for security professionals to test their skills and tools in a legal environment, to help web developers better understand the process of securing web applications, and to help teachers/students teach/learn in a classroom environment Web application security. The goal of DVWA is to practice some of the most common web vulnerabilities through a simple and straightforward interface, with varying degrees of difficulty. Please note that this software

Notepad++7.3.1
Easy-to-use and free code editor

SecLists
SecLists is the ultimate security tester's companion. It is a collection of various types of lists that are frequently used during security assessments, all in one place. SecLists helps make security testing more efficient and productive by conveniently providing all the lists a security tester might need. List types include usernames, passwords, URLs, fuzzing payloads, sensitive data patterns, web shells, and more. The tester can simply pull this repository onto a new test machine and he will have access to every type of list he needs.

SublimeText3 Mac version
God-level code editing software (SublimeText3)
