@kong-ui-public/spec-renderer-mini v0.5.1

@kong-ui-public/spec-renderer-mini

A Kong UI mini component for displaying API specs

• Features
• Requirements
• Usage
  • Install
  • Register
• Props
  • spec
  • tags
  • isFilterable
  • width
  • filterFunc
• Slots
  • item
  • empty-state
  • error-state
• Emits
  • selected
• Theming

Features

• Render spec styled object arrays
• Support both table of contents and list summary views

Requirements

• vue must be initialized in the host application

Usage

Install

Install the component in your host application

yarn add @kong-ui-public/spec-renderer-mini

Register

You can register portal-spec-renderer-mini globally or locally.

// Global registration
import { createApp } from 'vue'
import SpecRendererMini from '@kong-ui-public/spec-renderer-mini'
import '@kong-ui-public/spec-renderer-mini/dist/style.css'

const app = createApp(App)

app.use(SpecRendererMini)

<!-- Local registration -->
<template>
  <SpecRendererMini />
</template>

<script setup lang="ts">
import SpecRendererMini from '@kong-ui-public/spec-renderer-mini'
import '@kong-ui-public/spec-renderer-mini/dist/style.css'
</script>

Props

operations

• type: Object[]
• required: true

Operation object array. Required. The objects should conform to the following interface.

{
  /**
   * Relative operation path with optional path templating.
   * See https://swagger.io/specification/#paths-object
   */
  path: string
  /**
   * HTTP Method
   */
  method: string
  /**
   * Optional operationId
   */
  operationId: string | null
  /**
   * List of tag names for the operation used to group operations into sections
   */
  tags: string[]
  /**
   * Short summary of the operation
   */
  summary: string | null
  /**
   * Is the operation deprecated?
   */
  deprecated: boolean
}

tags

• type: Object[]
• required: false
• default: []

Object array for tags. You can use this to specify tag information such as description and externalDocs.

{
  /**
   * Tag name
   * See {@link Operation.tags} for usage details
   */
  name: string
  /**
   * Optional description.
   * CommonMark formatting is not supported at the moment.
   */
  description?: string
  /**
   * Optional link to external docs of the tag
   */
  externalDocs?: {
    description?: string
    url: string
  }
}

isFilterable

• type: Boolean
• required: false
• default: true

If enabled, will display filter input and enable filtering operations by tag names using case-insensitive partial matching.

width

• type: String
• required: false
• default: 210

Controls the width of the rendered spec. Currently supports numbers (will be converted to px), auto, vw, vh, and percentages for width.

filterFunction

• type: Function
• required: false

Overrides the default filter function. Provided function must return a list of Operation objects.

Example

const operationSummaryFilterFunc: OperationListFilterFunction = ({ items, query }) => {
  return items.filter((item) => item.summary.includes(query))
}

Slots

item

Controls the content of a single operation.

Slot props

item

• type: Object
• required: true

Operation object of the item to display.

select

• type: 'Function'
• required: true

Handler function to call when item is selected, usually on click event.

section

• type: String
• required: false

Section (tag) name or undefined if operation is untagged.

empty-state

Controls the content displayed when the spec array is empty.

error-state

Controls the content when spec is not provided.

Emits

selected

• returns: Object - the last clicked item data

{
  path: string
  method: string
  operationId: string | null
  tags: string[]
  summary: string | null
  deprecated: boolean
}

This is emitted whenever an item in the spec is clicked.

Theming