Web components

API documentation for any page

The apg-* custom elements document OpenAPI, Swagger 2.0, AsyncAPI, Protobuf and GraphQL APIs. Drop a whole reference into a page, or build your own from the parts.

An OpenAPI reference: navigation with search, servers and authentication.
An OpenAPI reference: navigation with search, servers and authentication.
One operation, with the request body example and a generated response example.
One operation, with the request body example and a generated response example.
A GraphQL schema: queries, mutations and subscriptions, and every type.
A GraphQL schema: queries, mutations and subscriptions, and every type.
A Protobuf file with gRPC services and every streaming kind, in the dark theme.
A Protobuf file with gRPC services and every streaming kind, in the dark theme.

Five standards, one set of components

  • OpenAPI 3.0 and 3.1Operations, schemas, webhooks, Try it out with every kind of authentication
  • Swagger 2.0Its own elements, picked by the reference automatically
  • AsyncAPI 3.0 and 3.1Servers, channels, operations, messages and bindings
  • Protobuf and gRPCServices by streaming kind, messages, enums, grpcurl and client samples
  • GraphQLQueries, mutations, subscriptions, types and Try it out

AsyncAPI, Protobuf and GraphQL documents are read by the same C++ engine as the CLI, compiled to WebAssembly.

A complete reference in one tag

<apg-api-reference> renders navigation with search, the overview, servers, authentication, every operation with Try it out, and the schemas. It picks the right elements for the kind of document it is given.

<apg-api-reference spec-url="/openapi.yaml"></apg-api-reference>

Or your own page, from the parts

Every part is an element of its own: the overview, one operation, one schema, the Try it out form, credentials, code samples. Parts that name the same document share it, including the chosen server and the credentials.

<apg-spec spec-url="/openapi.yaml">
  <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>

Install

The components are the npm package @mykulyak/apigenie-docs. Import them once, then use the elements in any page.

npm install @mykulyak/apigenie-docs
import "@mykulyak/apigenie-docs";                          // every element
import "@mykulyak/apigenie-docs/components/apg-operation";  // or just one

Any framework, or none

Standard custom elements built with Lit: plain HTML, a CMS, React, Vue, Svelte or Angular, with no bindings to install.

Rendered on the server

Pages can be prerendered with declarative shadow DOM, so search engines and readers without JavaScript see the whole reference.

Your look

Themed with CSS custom properties and ::part(), with light and dark palettes that follow the system setting.

A whole documentation site from the CLI

apigenie-generator docs turns any mix of OpenAPI, Swagger, AsyncAPI, Protobuf and GraphQL files into one static site built from these components, with translations, the git changelog of each API and example files.

apigenie-generator docs openapi.yaml events.asyncapi.yaml library.proto schema.graphql -o docs
cd docs && npm install && npm run build