Plugins

The elements render no x- extension of a document on their own. A plugin adds what a site needs: a renderer for each extension key it knows, views before or after the reference, a hook that changes Markdown before it is rendered, and hooks that run when the plugin starts and stops. Give plugins to <apg-api-reference> or <apg-spec> in their plugins property, as a list; the elements inside use them too. Elements that show the same document (the same spec-url, or an <apg-spec> around them) share its plugins: when two of them give a plugin with the same name, the first one is used.

import { html } from "lit";

const codeSamples = {
	name: "code-samples",
	extensions: {
		"x-codeSamples": ({ value }) => html`${value.map((sample) => html`<h4>${sample.lang}</h4><pre>${sample.source}</pre>`)}`,
	},
};

document.querySelector("apg-api-reference").plugins = [codeSamples];

A plugin is your own code: you bundle it or load it with the page like the elements. The elements never load a plugin from a URL.

A plugin

Field
name Lowercase letters, digits and dashes, unique among the plugins of a document.
extensions A renderer for each key, such as "x-codeSamples".
views Views with an id, a title, a position (start or end, the default), sidebar and a render function.
markdown(source) Returns the Markdown of a description, changed.
init(context) Runs when the plugin starts to be used for a document.
configChange(context) Runs when an attribute or property of the element that has the plugin changes.
destroy() Runs when the plugin is removed from plugins, or its element leaves the page.

The elements refuse a plugin with a bad name, a key that does not start with x-, or a field of the wrong type, and a second plugin with the same name. They report the refused plugin and use the rest.

The TypeScript types are exported from the package: DocsPlugin, PluginView, ExtensionRenderer, ExtensionRenderContext and DocsPluginContext.

Extension renderers

In an OpenAPI or Swagger 2.0 document, the elements look for x- keys on the document’s root and its info, on each tag and on each operation. A renderer gets:

Field
key The key, such as x-codeSamples.
value A copy of the key’s value. Changing it does not change the document.
target kind (document, info, tag or operation) and pointer, such as #/paths/~1pets/get.
auth, href, navigate The same as every hook gets (see below).

It returns a Lit template, a DOM node (a DocumentFragment too), text or nothing (null, undefined or Lit’s nothing). The elements show text as text, never as HTML, so a value from the document cannot add markup to the page. Each key’s output sits below the description, in a part="extension" element whose data-plugin and data-key attributes name the plugin and the key. When two plugins render the same key, the first one in plugins renders it.

A renderer runs again only when the value, the schemes that have credentials or the language change. A node it returns stays on the page while the operation updates for other reasons, such as typing in Try it out, so a widget keeps its state.

Views

A view shows its title as a heading, with what render(context) returns below it.

  • With layout="single", every view shows before the reference (position: "start") or after it.
  • With the sidebar, a view shows at the start or the end of the overview page.
  • With sidebar: true as well, the view gets an entry at the top or the bottom of the sidebar, and a page of its own at #/plugin/<name>/<id> (or <base-path>plugin/<name>/<id> with routing="history").

The Markdown hook

markdown(source) gets the Markdown of a description and returns it changed. The elements render and sanitize what it returns like the document’s own Markdown, so a hook can add Markdown but not HTML. For anything that needs markup, use an extension renderer or a view.

What every hook gets

Field
auth.authorized The names of the security schemes that have credentials.
auth.isAuthorized(scheme) Whether a scheme has credentials. Plugins never see the credentials themselves.
href(route) The URL of a page of the reference, such as { kind: "operation", slug: "listPets" }.
navigate(route) Goes to a page, as following a link to it would.

When a plugin fails

Each renderer runs in an error boundary. When it throws an error, or returns something the elements cannot show, the elements show a short message in its place: “The name plugin could not show this.” The rest of the page renders as usual. When a Markdown hook fails, the elements render the Markdown without it. When a lifecycle hook fails, the plugin stays in use.

The elements log every failure to the console with its stack, and fire apg-plugin-error once per failure:

reference.addEventListener("apg-plugin-error", (event) => {
	const { plugin, place, key, view, message } = event.detail;
	reportToMonitoring(plugin, place, key ?? view, message);
});

place is plugin (refused), extension, view, markdown, init, configChange or destroy.

The boundary catches errors that happen while the elements render. An error a plugin’s own node throws later, from an event handler or a timer, is outside it.

Server-side rendering

renderApiReference renders without plugins. In the browser, the elements add plugin output once they have hydrated, so the hydrated page first matches the server’s. Give a server-rendered reference its plugins itself: another element that shows the same document and gives plugins as the page hydrates would add their output before hydration is over.

Part
extensions What plugins render for the x- keys of the document, a tag or an operation.
extension One key’s output.
plugin-error The message a failed renderer shows in place of its output.
plugin-view A view.
Last updated on View as Markdown
Was this helpful?