Doc components

One API, documented from four standards

Carpet Express, a fictional parcel carrier, is described in OpenAPI, AsyncAPI, GraphQL and Protobuf. Every reference below is rendered in this page by @mykulyak/apigenie-docs 0.1.0, the package you install.

A complete reference from one tag

Pick a standard. One element, <apg-api-reference>, reads each document and shows search, navigation, operations, messages and types. Its tag is under the reference. Links inside the reference change the part of the address after #, so the back button works.

On the OpenAPI and GraphQL tabs, Try it out builds the request and its code samples, but sending fails. Carpet Express is fictional: its servers under carpetexpress.example do not resolve, and this site serves no /graphql. To send to a server of your own, choose Custom URL or type a GraphQL endpoint. That server must allow requests from https://apigenie.pl (CORS).

The Protobuf tab shows the Carpet Express services and messages as one file, merged from nine. The components document one .proto file and resolve only the files they bundle: the well-known types of google/protobuf and a few files of google/api, google/rpc and grpc.

<apg-api-reference spec-url="/doc-components/carpet-express/openapi/carpet-express.openapi-31.yaml">
</apg-api-reference>

Your own page, from the parts

Put one operation and one schema between your own paragraphs. <apg-spec> loads the document once and shares it with the parts inside it.

<apg-spec spec-url="/doc-components/carpet-express/openapi/carpet-express.openapi-31.yaml">
  <h3>Track a parcel</h3>
  <p>The tracking page calls one endpoint. It needs no API key.</p>
  <apg-operation operation-id="getPublicTracking"></apg-operation>
  <apg-schema name="PublicTracking" depth="1" with-example></apg-schema>
</apg-spec>

Track a parcel

The tracking page calls one endpoint. It needs no API key.

Your colors and type, through CSS

CSS custom properties and ::part() reach inside the components; the rest of your styles stay out. Pick a look to apply its CSS to the operation below. The light and dark palettes follow the theme switch of this site.

/* no tokens set: the built-in palette */

Put them on your page

Install the package, import it once, and add the tags. AsyncAPI, GraphQL and Protobuf documents also need the WebAssembly modules in the package's dist/wasm/, served by your site. The doc components referencelists the attributes, events, slots and CSS parts of every element.

npm install @mykulyak/apigenie-docs
import "@mykulyak/apigenie-docs";
Embed an API referenceBack to Doc components