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><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>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. The doc components referencelists the attributes, events, slots and CSS parts of every element.
npm install @mykulyak/apigenie-docsimport "@mykulyak/apigenie-docs";