OpenAPI elements

The elements of OpenAPI 3.0 and 3.1 documents. <apg-nav>, <apg-schema>, <apg-try-it>, <apg-auth>, <apg-servers> and <apg-code-samples> show Swagger 2.0 documents as well; Swagger 2.0 elements lists the elements of their own.

Operations are selected with operation-id, or with method and path; schemas with name (in components.schemas) or pointer.

<apg-overview>

Title, version, description, contact, license and external documentation of the API.

Loaded on its own with import "@mykulyak/apigenie-docs/components/apg-overview";.

Attributes

Attribute Property Type Default Description
heading-level headingLevel number 1 Level of the title heading (1–6).

And spec-url, spec, api and theme, like every element that shows a document: Where the document comes from.

CSS parts

Part Description
overview The container.
title The API title (h1 unless heading-level says otherwise).
version Version badges.
info Contact, license and terms line.
link Links in the info line.

Forwarded from the elements inside it:

<apg-operation>

Documentation of one operation: parameters, request body, responses (with examples and schemas), security and callbacks, with an optional embedded Try it out.

Loaded on its own with import "@mykulyak/apigenie-docs/components/apg-operation";.

Attributes

Attribute Property Type Default Description
operation-id operationId string The operation, by operationId.
method method string The operation by method and path (alternative to operation-id).
path path string The path of the operation, with method.
pointer pointer string The operation by JSON pointer.
try-it tryIt "inline" | "open" | "none" "inline" inline: a button shows Try it out; open: shown from the start; none: hidden.
heading-level headingLevel number 2 Level of the path heading.
lazy lazy boolean false Render only the header until the operation comes near the viewport (used for long pages; the full content is always rendered on the server).

And spec-url, spec, api and theme, like every element that shows a document: Where the document comes from.

Methods

Method Description
reveal() Renders the full content of a lazy operation.

Events

Event Description
apg-navigate A tag link was followed; cancelable.

Slots

Slot Description
before Content shown after the header.
after Content shown at the end.

CSS parts

Part Description
operation The container.
header The header with method, path and summary.
path The path.
summary The summary line.
section Sections (parameters, body, responses).
section-title Section headings.
table Tables.
parameter-name Parameter names.
type Type labels of parameters and headers.
required Required markers.
select The media type and example choices.
tab Example and schema tabs; the selected one also has tab-active.
tab-active The selected tab.
badge Badges (deprecated, webhook).
tag-link Links to tag pages.
response One response.
response-status Its status code.
try-it-button The button that shows Try it out.

Forwarded from the elements inside it:

<apg-schema>

Schema as an expandable tree: properties, items, combinators, constraints, enums, defaults and examples. Referenced schemas beyond the inline depth and recursive references expand on click.

Loaded on its own with import "@mykulyak/apigenie-docs/components/apg-schema";.

Attributes

Attribute Property Type Default Description
name name string Name of a schema in components.schemas.
pointer pointer string JSON pointer of the schema (alternative to name).
depth depth number 1 Levels of properties shown initially (1: the schema’s own properties).
with-example withExample boolean false Show Schema / Example tabs with an example generated from the schema.
hide-description hideDescription boolean false Hide the root description (when the surrounding page shows it).

And spec-url, spec, api and theme, like every element that shows a document: Where the document comes from.

Properties

Property Type Description
node SchemaNode A schema view model to render directly (used by <apg-operation>).

Events

Event Description
apg-navigate A schema link was followed; cancelable.

CSS parts

Part Description
schema The tree.
schema-row One property line.
property-name Property name.
type Type label.
required Required marker.
toggle Expand/collapse button.
ref-link Link to a component schema’s page.
format-link Link to the specification of a format.
constraint Constraint or fact (enum, default, pattern, …).
tab Schema and example tabs (with-example); the selected one also has tab-active.
tab-active The selected tab.

Forwarded from the elements inside it:

<apg-try-it>

Sends requests to the API: parameters, request body (text, forms, file uploads), server and credentials, with a live URL preview, code samples and a response viewer that streams server-sent events and NDJSON.

Events: apg-request (cancelable; detail.request may be replaced) before sending and apg-response afterwards.

Loaded on its own with import "@mykulyak/apigenie-docs/components/apg-try-it";.

Attributes

Attribute Property Type Default Description
operation-id operationId string The operation, by operationId.
method method string The operation by method and path (alternative to operation-id).
path path string The path of the operation, with method.
pointer pointer string The operation by JSON pointer (used by <apg-operation>).
hide-samples hideSamples boolean false Hide the code samples.

And spec-url, spec, api and theme, like every element that shows a document: Where the document comes from.

Events

Event Description
apg-request Before a request is sent; cancelable, detail.request may be replaced.
apg-response After a response (or failure).

CSS parts

Part Description
try-it The container.
section-title Headings of the form’s sections.
label Field labels.
input Text inputs.
select Selects.
textarea Body and JSON editors.
button Secondary buttons.
button-primary The Send button.
url The request URL.
problems Problems that block or affect the request.
response The response viewer.
response-status The response status code.
cors What a cross-origin request needs from the server, when it failed before a response.
tab Response tabs; the selected one also has tab-active.
tab-active The selected tab.

Forwarded from the elements inside it:

<apg-auth>

Credentials for the API’s security schemes: API keys, HTTP Basic and Bearer, OAuth 2.0 flows (authorization code with PKCE, client credentials, implicit, password) and OpenID Connect discovery. A token can always be pasted instead of running a flow.

Loaded on its own with import "@mykulyak/apigenie-docs/components/apg-auth";.

Attributes

Attribute Property Type Default Description
schemes schemes string Comma-separated scheme names to show; all schemes by default.

And spec-url, spec, api and theme, like every element that shows a document: Where the document comes from.

Events

Event Description
apg-auth-change Credentials of a scheme were set or cleared.

CSS parts

Part Description
auth The container.
scheme One security scheme.
scheme-name The scheme’s name.
status Authorized / not authorized.
label Field labels.
input Inputs.
select Flow selection.
button Secondary buttons.
button-primary Authorize buttons.

Forwarded from the elements inside it:

<apg-servers>

Chooses the server Try it out sends requests to: a declared server with its variables, or a custom URL. The choice is shared by every component showing the same API.

Loaded on its own with import "@mykulyak/apigenie-docs/components/apg-servers";.

Attributes

Only spec-url, spec, api and theme, like every element that shows a document: Where the document comes from.

CSS parts

Part Description
servers The container.
label Field labels.
select The server list and enumerated variables.
input Variable and custom URL inputs.
url The resolved server URL.

<apg-code-samples>

Code samples for a request: curl, JavaScript (fetch) and Python (requests). Shows the request of an operation’s Try-it-out form (credentials masked), or request when set.

Loaded on its own with import "@mykulyak/apigenie-docs/components/apg-code-samples";.

Attributes

Attribute Property Type Default Description
operation-id operationId string Operation whose Try-it-out request is shown (by operationId).
method method string Operation by method and path (alternative to operation-id).
path path string The path of the operation, with method.
languages languages string "curl,javascript,python" Comma-separated languages: curl, javascript, python.

And spec-url, spec, api and theme, like every element that shows a document: Where the document comes from.

Properties

Property Type Description
request BuiltRequest A request to show instead of an operation’s.

CSS parts

Part Description
code-samples The container.
tab Language tabs; the selected one also has tab-active.
tab-active The selected tab.

Forwarded from the elements inside it:

Last updated on Edit this page on GitHubView as Markdown
Was this helpful?