Kong's open-source spec renderer.
An online API specification editor is available at api-documentation.dev, and you can view the extended usage example in the source repository.
Install the @kong/spec-renderer package in your host project.
pnpm add @kong/spec-rendererImport the package and the component(s) you wish to use.
<template>
<SpecDocument
:spec="spec"
/>
</template>
<script setup lang="ts">
import { SpecDocument } from '@kong/spec-renderer'
const spec= `openapi: 3.1.0
info:
title: Beer API
description: API for managing beers
version: 1.0.0
...`
</scirpt>Import the package (and TypeScript types, if desired) inside of your App's entry file (e.g. for Vue, main.ts). Set the plugin options, and tell Vue to use the plugin.
// main.ts
import App from './App.vue'
import KongSpecRendererPlugin from '@kong/spec-renderer'
import '@kong/spec-renderer/dist/style.css'
const app = createApp(App)
// Register the plugin
app.use(KongSpecRendererPlugin)
app.mount('#app')Now that the plugin is globally registered, simply include a component just like you would any other Vue component, utilizing any props as needed
This is to renderer KongSpecRender component
<template>
<KongSpecRenderer
:spec="specification-content-to-present"
/>
</template>This is to renderer Toc and Document components separately
<template>
<div id="kong-spec-renderer-wrapper">
<nav>
<KongSpecRendererToc
:table-of-contents="tableOfContents.value"
/>
</nav>
<main>
<KongSpecRendererDocument
:document="parsedDocument.value"
current-path="/"
/>
</main>
</div>
</template>
<script setup lang="ts">
import { onBeforeMount } from 'vue'
import { parseSpecDocument, parsedDocument, tableOfContents } from '@kong/spec-renderer'
onBeforeMount(() => async {
await parseSpecDocument()
}
</script>This is to renderer SchemaRenderer component
<template>
<KongSchemaRenderer
:schema="mySchema"
/>
</template>
<script setup lang="ts">
import { SchemaObject } from '@kong/spec-renderer'
const mySchema: SchemaObject = {
type: 'object',
title: 'Person',
properties: {
name: {
type: 'string',
},
},
}
</script>Import the package and call the provided registerSpecRenderer function.
// IMPORTANT: we are importing from the web-component bundle
import { registerKongSpecRenderer, parseSpecDocument, parsedDocument, tableOfContents } from '@kong/spec-renderer/web-component'
// Call the registration function to automatically register all spec-renderer custom elements for usage
registerKongSpecRenderer()
// this is to renderer spec-renderer as one single component
const singleComponent = () => (
<kong-spec-renderer
spec="openapi: 3.1.0 ..."
/>
)
// this is to renderer toc and document separately
const tocAndDocComponents = async () => {
await parseSpecDocument(spec, {webComponentSafe: true})
return (
<div id="kong-spec-renderer-wrapper">
<nav>
<kong-spec-renderer-toc
table-of-contents={tableOfContents.value}
/>
</nav>
<main>
<kong-spec-renderer-document
document={parsedDocument.value}
current-path="/"
/>
</main>
</div>
)
}<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@kong/spec-renderer@^1/dist/spec-renderer.css" />
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@100..900&family=JetBrains+Mono:ital,wght@0,100..800;1,100..800&display=swap" rel="stylesheet">
<style>
body { font-family: 'Inter', Roboto, Helvetica, sans-serif; }
</style>
</head>
<body>
<kong-spec-renderer
spec-url="https://raw.githubusercontent.com/Kong/spec-renderer/refs/heads/main/sandbox/public/specs/beer-and-coffee.yaml"
navigation-type="hash"
/>
<script type="module">
import { registerKongSpecRenderer } from 'https://cdn.jsdelivr.net/npm/@kong/spec-renderer@^1/dist/kong-spec-renderer.web-component.es.js'
registerKongSpecRenderer()
</script>
</body>
</html>As of now only SpecRenderer as single component is supported for this. Let us know if support for individual SpecRendererToc, SpeRendererDocument and SchemaRenderer is needed.
Check out the SpecRendererProps interface for all props valid for the SpecRenderer component.
To get started, install the package dependencies
pnpm installThis repository includes a Vue sandbox app (see the /sandbox directory) to allow you to experiment with components.
To build and run a local preview of the Sandbox:
pnpm run previewLint package files, and optionally auto-fix detected issues.
# Stylelint only
pnpm run stylelint
# Stylelint and fix
pnpm run stylelint:fix
# ESLint only
pnpm run lint
# ESLint and fix
pnpm run lint:fixUnit and component tests are run with Vitest.
# Run tests
pnpm run test
# Run tests in the Vitest UI
pnpm run test:openpnpm run build
This repo uses Conventional Commits.
Commitizen and Commitlint are used to help build and enforce commit messages.
It is highly recommended to use the following command in order to create your commits:
pnpm run commitThis will trigger the Commitizen interactive prompt for building your commit message.
Lefthook is used to manage Git Hooks within the repo.
- A
commit-msghook is automatically setup that enforces commit message stands withcommitlint, seelefthook.ymal - A
pre-pushhook is used that runseslintbefore allowing you to push your changes to the repository
Additionally, CI will use commitlint to validate the commits associated with a PR in the Lint and Validate job.
- All pull requests require review and approval from authorized team members.
- Automated approvals through workflows are strictly prohibited.
- There is an exception for automated pull request approvals originating from generated dependency updates that satisfy status checks and other requirements.
- Protected branches require at least one approval from code owners.
- All status checks must pass before a pull request may be merged.
This repository utilizes Semantic Release for automated package publishing and version updates.
-
Thank You Stoplight for beautiful parser and AST producer stoplight/http-spec.
-
Thank You Stoplight for excellent approach for dealing with specification's table of contents and specification's security definitions. Found in elements and currently placed into src/stoplight, while PR back to elements package pending.
-
Thank You AsyncApi for superb @asyncapi/parser.