apg-api-reference and apg-spec

<apg-api-reference> renders a whole reference from one tag: navigation with search, the overview, servers, authentication, the operations with Try it out, and the schemas. For an AsyncAPI document, a Protobuf file or a GraphQL schema it uses the elements of that standard. <apg-spec> loads a document and shares it with the elements inside it, for a page of your own design. Both carry the settings of Try it out (Try it out).

A page of your own from parts

<apg-spec spec-url="/openapi.yaml" oauth2-client-id="docs-site">
	<apg-overview></apg-overview>
	<h2>Quick start</h2>
	<apg-auth schemes="ApiKey"></apg-auth>
	<apg-operation operation-id="getPet" try-it="none"></apg-operation>
	<apg-try-it operation-id="getPet"></apg-try-it>
	<apg-schema name="Pet" depth="2" with-example></apg-schema>
</apg-spec>

Operations are selected with operation-id, or with method and path. The pages of AsyncAPI, Protobuf and GraphQL elements show the same page for their standards.

Pages and routes

With layout="sidebar", the default, <apg-api-reference> shows one page at a time and keeps it in the URL as routing says:

routing The URL of an operation’s page
hash (default) #/operation/getPet
history <base-path>/operation/getPet; the server must serve the reference’s page for these paths.
none Unchanged; route names the page, as in server-side rendering.

route takes operation/getPet, tag/pets or schema/Pet; for AsyncAPI channel/orders or message/orderCreated; for Protobuf service/LibraryService, method/LibraryService.GetBook, message/Book or enum/Genre; for GraphQL operation/query.books, type/Book or directive/auth. layout="single" shows every page one after the other and scrolls to the target. Links between pages emit the cancelable apg-navigate event: cancel it to route with your application’s router.

<apg-api-reference>

An API reference: navigation with search, overview, servers, authentication, operations grouped by tag with Try it out, and schemas. It is built from the public parts (<apg-nav>, <apg-operation>, …) and forwards their CSS parts. Swagger 2.0 documents are shown with the apg-swagger-* parts (overview, hosts, security definitions, operations) and their schemas are called definitions. AsyncAPI 3 documents are shown with the apg-asyncapi-* parts: overview, servers and security schemes, then pages for operations, channels, messages and schemas. Protobuf files are shown with the apg-protobuf-* parts: an overview with the services, then pages for services, gRPC methods, messages and enums. GraphQL schemas are shown with the apg-graphql-* parts: an overview with the queries, mutations and subscriptions, then pages for operations (with Try it out), types and directives.

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

Attributes

Attribute Property Type Default Description
layout layout "sidebar" | "single" "sidebar" sidebar (one page at a time) or single (everything on one page).
routing routing RoutingMode "hash" How the current page is kept in the URL: hash, history or none.
base-path basePath string "/" With routing="history": the path the reference is mounted at, such as /docs.
route route string Page to show, such as operation/getPet (used by server-side rendering and with routing="none").
hide-try-it hideTryIt boolean false Hides Try it out, and the server and credential choices it needs.
hide-schemas hideSchemas boolean false Hides the schemas (definitions in Swagger 2.0) from the overview and the navigation.
show-problems showProblems boolean false Show problems found in the document (unresolved references, validation issues).
changelog-url changelogUrl string URL of the changelog of a docs bundle (changelog.json), fetched in the browser; adds the Changelog page.
proxy-url proxyUrl string CORS proxy: https://proxy.example/?url={url}, or a prefix the request URL is appended to.
credentials credentials RequestCredentials "same-origin" Credentials mode of Try-it-out requests: omit, same-origin or include.
timeout timeout number 30000 Try-it-out timeout in milliseconds.
max-response-bytes maxResponseBytes number 5242880 Response bodies larger than this many bytes (5 MiB) are truncated.
persist-auth persistAuth PersistMode Keep credentials across page loads: session or local storage (default: memory only).
oauth2-redirect-url oauth2RedirectUrl string Redirect page registered with the OAuth 2.0 authorization server.
oauth2-client-id oauth2ClientId string OAuth 2.0 client ID used by every OAuth 2.0 / OpenID Connect scheme without its own authConfig.
schema-depth schemaDepth number 6 Levels of referenced schemas expanded inline.
asyncapi-wasm-url asyncapiWasmUrl string URL of the asyncapi WebAssembly module (asyncapi.web.mjs, with asyncapi.web.wasm next to it), which reads AsyncAPI documents; loaded when one is shown.
protobuf-wasm-url protobufWasmUrl string URL of the protobuf WebAssembly module (protobuf.web.mjs, with protobuf.web.wasm next to it), which reads .proto documents; loaded when one is shown.
graphql-wasm-url graphqlWasmUrl string URL of the graphql WebAssembly module (graphql.web.mjs, with graphql.web.wasm next to it), which reads GraphQL schemas; loaded when one is shown.
graphql-endpoint graphqlEndpoint string The URL GraphQL operations are sent to (default: /graphql on the origin of the document).

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

Properties

Property Type Description
changelog ChangelogFile The changelog of a docs bundle, as a value; adds the Changelog page.
examples ExampleFile[] The example files of a docs bundle, shown on the overview or on the operation they are named after.
locales LocaleLink[] The same page in other languages (a docs bundle with several locales): the locale switcher of the sidebar.
authConfig Record<string, OAuthClientConfig> OAuth 2.0 client settings per security scheme.
fetch typeof fetch fetch used by Try it out (for example to add tracing).
requestInterceptor ApiSettings["requestInterceptor"] Called with every Try-it-out request before it is sent.
responseInterceptor ApiSettings["responseInterceptor"] Called with every Try-it-out response.
parserEngine ParserEngine Parser of documents given as text (default: the JavaScript parser).
asyncapiEngine AsyncApiEngine Reads AsyncAPI documents (instead of asyncapi-wasm-url).
protobufEngine ProtobufEngine Reads .proto documents (instead of protobuf-wasm-url).
graphqlEngine GraphQLEngine Reads GraphQL schemas (instead of graphql-wasm-url).

Methods

Method Description
navigate(route) Shows a page (and records it in the URL unless routing="none").

Events

Event Description
apg-navigate A link was followed; cancel it to route yourself.
apg-spec-load The document was parsed.
apg-spec-error The document could not be loaded or parsed.

Slots

Slot Description
logo Shown at the top of the sidebar.
header Shown above the content.
intro Shown on the overview page, before the API description.
footer Shown after the content.

CSS parts

Part Description
reference The layout grid.
sidebar The sidebar.
content The main content.
menu-button Opens the sidebar on narrow screens.
page-title Headings of tag and schema pages.
problems The problems panel (show-problems).
operation-link Operation links in the overview’s index.
channel-link Channel links in the overview’s index (AsyncAPI).
message-link Message links in the overview’s index (AsyncAPI, Protobuf).
service-link Service links in the overview’s index (Protobuf).
method-link Method links in the overview’s index (Protobuf).
enum-link Enum links in the overview’s index (Protobuf).
type-link Type links in the overview’s index (GraphQL).
directive-link Directive links in the overview’s index (GraphQL).
section-title Headings of the overview’s sections (servers, authentication, operations, …).
address Channel addresses in the overview’s index (AsyncAPI).
locales The language switcher, when the reference has locales.
locale One language in it.
examples The example files of the overview or of a GraphQL operation (examples).
example-title The name of an example file, with its download link.

Forwarded from the elements inside it:

CSS custom properties

Property Description
--apg-sidebar-width Width of the sidebar.
--apg-content-width Maximum width of the content.
--apg-sticky-top Offset of the sticky sidebar (height of a fixed page header).

<apg-spec>

Loads an API document (OpenAPI, Swagger 2.0, AsyncAPI, Protobuf or GraphQL) and shares it with the elements inside it, which then need no spec-url of their own. It renders nothing but its content.

The document comes from spec-url, the spec property or a child <script type="application/yaml" data-spec>…</script> (for a CMS). The Try-it-out settings (proxy-url, credentials, persist-auth, authConfig, …) apply to every element inside.

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

Attributes

Attribute Property Type Default Description
proxy-url proxyUrl string CORS proxy: https://proxy.example/?url={url}, or a prefix the request URL is appended to.
credentials credentials RequestCredentials "same-origin" Credentials mode of Try-it-out requests: omit, same-origin or include.
timeout timeout number 30000 Try-it-out timeout in milliseconds.
max-response-bytes maxResponseBytes number 5242880 Response bodies larger than this many bytes (5 MiB) are truncated.
persist-auth persistAuth PersistMode Keep credentials across page loads: session or local storage (default: memory only).
oauth2-redirect-url oauth2RedirectUrl string Redirect page registered with the OAuth 2.0 authorization server.
oauth2-client-id oauth2ClientId string OAuth 2.0 client ID used by every OAuth 2.0 / OpenID Connect scheme without its own authConfig.
schema-depth schemaDepth number 6 Levels of referenced schemas expanded inline.
asyncapi-wasm-url asyncapiWasmUrl string URL of the asyncapi WebAssembly module (asyncapi.web.mjs, with asyncapi.web.wasm next to it), which reads AsyncAPI documents; loaded when one is shown.
protobuf-wasm-url protobufWasmUrl string URL of the protobuf WebAssembly module (protobuf.web.mjs, with protobuf.web.wasm next to it), which reads .proto documents; loaded when one is shown.
graphql-wasm-url graphqlWasmUrl string URL of the graphql WebAssembly module (graphql.web.mjs, with graphql.web.wasm next to it), which reads GraphQL schemas; loaded when one is shown.
graphql-endpoint graphqlEndpoint string The URL GraphQL operations are sent to (default: /graphql on the origin of the document).

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

Properties

Property Type Description
authConfig Record<string, OAuthClientConfig> OAuth 2.0 client settings per security scheme.
fetch typeof fetch fetch used by Try it out (for example to add tracing).
requestInterceptor ApiSettings["requestInterceptor"] Called with every Try-it-out request before it is sent.
responseInterceptor ApiSettings["responseInterceptor"] Called with every Try-it-out response.
parserEngine ParserEngine Parser of documents given as text (default: the JavaScript parser).
asyncapiEngine AsyncApiEngine Reads AsyncAPI documents (instead of asyncapi-wasm-url).
protobufEngine ProtobufEngine Reads .proto documents (instead of protobuf-wasm-url).
graphqlEngine GraphQLEngine Reads GraphQL schemas (instead of graphql-wasm-url).

Events

Event Description
apg-spec-load The document was parsed.
apg-spec-error The document could not be loaded or parsed.

Slots

Slot Description
(default) Components and any other content.

<apg-nav>

Navigation: operations grouped by tag, webhooks and schemas, with search. For AsyncAPI documents: operations, channels, messages and schemas. For Protobuf files: services with their methods, messages and enums. A document of a docs bundle with a changelog gets a Changelog item.

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

Attributes

Attribute Property Type Default Description
filter filter string "" Initial search text.
hide-search hideSearch boolean false Hides the search input.
hide-schemas hideSchemas boolean false Leaves the schemas out of the navigation.

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

Properties

Property Type Description
route Route The page shown, highlighted in the list.

Events

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

CSS parts

Part Description
nav The <nav> element.
search The search input.
nav-group A group (tag, webhooks, schemas).
nav-group-title A group’s title link or label.
nav-item A link; the current page’s link also has nav-item-active.
nav-item-active The current page’s link.

Forwarded from the elements inside it:

<apg-changelog>

The git changelog of a document, as apigenie-generator docs --changelog writes it into the docs bundle (changelog.json): by revision (newest first; what each release or commit added, removed, deprecated or changed, with a badge for breaking changes), or the history of each operation (view="items"). Items link to their pages when the document has them. The changelog comes from the changelog property, or from the docs bundle of the enclosing <apg-api-reference>.

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

Attributes

Attribute Property Type Default Description
view view "revisions" | "items" "revisions" revisions (newest first) or items (the history of each operation or method).
heading-level headingLevel "1" | "2" | "3" "2" Level of the title heading.

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

Properties

Property Type Description
changelog ChangelogFile The changelog; by default the one of the docs bundle of the enclosing reference.

CSS parts

Part Description
changelog The root element.
page-title The heading of the changelog.
entry One revision.
revision The heading of a revision.
badge A severity or change badge.
section-title The title of a section of a revision (Operations, Channels, …).
item One changed item.
item-link The link of an item to its page.
history The history of one item (view="items").
Last updated on Edit this page on GitHubView as Markdown
Was this helpful?