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: trueas 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>withrouting="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. |