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. The same element reads each document and shows search, navigation, operations, messages and types. Links inside the reference change the part of the address after #, so the back button works.
<apg-api-reference spec-url="/doc-components/carpet-express/openapi/carpet-express.openapi-31.yaml">
</apg-api-reference><apg-api-reference spec-url="/doc-components/carpet-express/asyncapi/carpet-express.asyncapi.yaml"
asyncapi-wasm-url="/doc-components/wasm/asyncapi.web.mjs">
</apg-api-reference><apg-api-reference spec-url="/doc-components/carpet-express/graphql/carpet-express.graphql"
graphql-wasm-url="/doc-components/wasm/graphql.web.mjs">
</apg-api-reference><apg-api-reference spec-url="/doc-components/carpet-express/protobuf/carpet-express.proto"
protobuf-wasm-url="/doc-components/wasm/protobuf.web.mjs">
</apg-api-reference>Carpet Express does not exist, so Try it out builds the request and its code samples, and sending it fails: the hosts under carpetexpress.example do not resolve. The Protobuf file is the fixture's nine files in one, because the components document one .proto file and resolve only the standard imports.
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 */apg-spec {
--apg-color-accent: #b4451f;
--apg-font-sans: Georgia, serif;
--apg-radius: 2px;
}apg-spec {
--apg-color-accent: #2f7d4f;
--apg-method-get: #2f7d4f;
--apg-radius: 14px;
}
apg-spec::part(method) {
border-radius: 999px;
}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.
npm install @mykulyak/apigenie-docsimport "@mykulyak/apigenie-docs";