Forem: Ola B

Create elegant OpenAPI spec documentation with Rapi Doc and Vitepress

Ola B — Sat, 23 Nov 2024 17:32:44 +0000

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 />

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>

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!

Animate your SVG text with animejs (and Vue)

Ola B — Thu, 18 May 2023 21:56:07 +0000

Are you looking for a non-standard portfolio page welcome text? Do you want to create an animated website to propose to your loved one?

Say no more!

In this #showdev I'll teach you how to create stunning SVG animation with an equally stunning animejs library!

The result will look like this:

NOTE: This post will show you how to create a line drawing animation in animejs. If you want it in a condensed form, straight from the source, visit the official documentation.

Prerequisites

To create a stunning animated SVG image, first, you will need SVG to animate. There are many tools to do that, available both online and offline. You can, for example, start with generating text using easysvg (written in php, but a great tool nonetheless).

Important: Every letter in your SVG should be a separate <path> tag! Here paths mark the outlines of the letters.

You will also need a container to run the animation in. It can be anything, pure JS script or a more advanced app. In my case, I'm using a very simple Vue.js app.

Preparing your SVG

To make our SVG look classy, we need to tweak it a bit:

To provide it with an "outlined" look, set fill attribute in every <path> tag to transparent and set stroke attribute to any color you want.
Add some extra elements for flavor - directly in SVG code (if you're the pro and a math nerd) or use some editor to do it.

Use my SVG, if you want: link to github file.

Animating

First, install animejs.

juliangarnier / anime

JavaScript animation engine

Anime.js

Anime.js is a fast, multipurpose and lightweight JavaScript animation library with a simple, yet powerful API.
It works with CSS properties, SVG, DOM attributes and JavaScript Objects

Usage

Anime.js V4 works by importing ES modules like so:

import {
  animate,
  stagger,
} from 'animejs';

animate('.square', {
  x: 320,
  rotate: { from: -180 },
  duration: 1250,
  delay: stagger(65, { from: 'center' }),
  ease: 'inOutQuint',
  loop: true,
  alternate: true
});

V4 Documentation

The full documentation is available here.

V3 Migration guide

You can find the v3 to v4 migration guide…

View on GitHub

Then add animejs animation:

anime({
    targets: document.getElementsByTagName('svg')[0].children,
    strokeDashoffset: [anime.setDashoffset, 0],
    easing: 'easeInOutBack',
    delay: function(el, i) { return i * 250 },
    direction: 'normal',
  });

Easy? Let me break it down line by line!

    targets: document.getElementsByTagName('svg')[0].children,

In this line, we point to every element we want to animate, in this case to an array of every child element of our SVG. You may need to adjust it a little to the structure of your SVG.

    strokeDashoffset: [anime.setDashoffset, 0],

This is what makes animation happen. It uses stroke-dashoffset attribute. If you want to know more about animating SVGs using this attribute, I recommend this CSS Tricks article.

    easing: 'easeInOutBack',

I wanted to add a little "bouncing" at the beginning and the end of the animation of every letter. If you want to test different easing functions on your own, I recommend easings.net.

    delay: function(el, i) { return i * 250 },

I wanted to slightly delay every animated path, so I passed a function that multiplies the delay by the index of an element in the table I passed in targets.

    direction: 'normal',

You can choose from normal, reverse, and alternate.

Embed this... somewhere

Although animejs can be used in Vanilla, I really wanted to use it in my Vue.js app.

I used Vue.js transitions to do that. More on them.

First, template:

<Transition appear :css="false" @enter="onEnter" name="howdy">
  <!-- Your SVG goes here. I used v-html because I'm lazy ¯\_(ツ)_/¯  -->
  <div v-html="howdy" />
</Transition>

You can use SVG Component to embed your SVG on a page.

I wanted my animation to start on a component render, so I added appear keyword to the transitions. I also needed to tell Vue this animation would be purely JS, so I used :css="false".

Now I only need to write onEnter callback:

const onEnter = (el: Element, done: () => void) => {
  anime({
    targets: el.getElementsByTagName('svg')[0].children,
    strokeDashoffset: [anime.setDashoffset, 0],
    easing: 'easeInOutBack',
    delay: function(el, i) { return i * 250 },
    direction: 'normal',
    complete: () => {
      done();
    },
  });
}

onEnter uses the Transition Element as the first argument and done() function as the second. We have to call done() function at the end of the application to signal to Vue that the animation ended. We can use complete hook from animejs to do it.
And we want to animate only descendants of our Transition element, so we can specify targets using the first argument.

And... that's it! Sit back and enjoy your animated text!

If you have any questions, I'm happy to answer :) If there's anything to be improved in this short post, let me know, and I'll gladly fix that!

And if you want to see this animation in action, you can visit my page (I have to warn you though, this is still in a WIP stage).

All the best,

Aleksandra (or Ola, for short)