# @mykulyak/apigenie-docs

Source: https://apigenie.pl/docs/reference/doc-components
See also: [apg-api-reference and apg-spec](https://apigenie.pl/docs/reference/doc-components/reference-and-spec.md), [OpenAPI elements](https://apigenie.pl/docs/reference/doc-components/openapi.md), [Swagger 2.0 elements](https://apigenie.pl/docs/reference/doc-components/swagger.md), [AsyncAPI elements](https://apigenie.pl/docs/reference/doc-components/asyncapi.md), [Protobuf and gRPC elements](https://apigenie.pl/docs/reference/doc-components/protobuf.md), [GraphQL elements](https://apigenie.pl/docs/reference/doc-components/graphql.md), [Building blocks](https://apigenie.pl/docs/reference/doc-components/building-blocks.md), [Try it out](https://apigenie.pl/docs/reference/doc-components/try-it-out.md), [Theming](https://apigenie.pl/docs/reference/doc-components/theming.md), [Server-side rendering](https://apigenie.pl/docs/reference/doc-components/server-side-rendering.md), [apigenie-docs build](https://apigenie.pl/docs/reference/doc-components/docs-build.md).

The npm package `@mykulyak/apigenie-docs` holds the doc components: standard custom elements, built
with Lit, that document OpenAPI 3.0 and 3.1, Swagger 2.0, AsyncAPI 3.0 and 3.1, Protobuf (proto3)
and GraphQL APIs on a page, with Try it out for OpenAPI, Swagger 2.0 and GraphQL. It also holds
`apigenie-docs build`, which renders the docs bundle of `apigenie-generator docs` into a static
site ([apigenie-docs build](/docs/reference/doc-components/docs-build)).

The [live examples](/tools/doc-components/examples) render one API in OpenAPI, AsyncAPI, GraphQL
and Protobuf with these elements. The guide
[Publish API documentation](/docs/guides/publish-api-documentation#or-put-a-reference-into-your-own-page)
puts a reference into a page.

## Loading the elements

| Where | How |
| --- | --- |
| Plain HTML or a CMS | `<script type="module" src="…/apigenie-web-components.js"></script>`, the file in the package's `dist/cdn/`. |
| A bundler, every element | `import "@mykulyak/apigenie-docs";` |
| A bundler, one element | `import "@mykulyak/apigenie-docs/components/apg-operation";` |
| Server-side rendering | `@mykulyak/apigenie-docs/ssr`, then the `hydrate` entry point in the browser ([Server-side rendering](/docs/reference/doc-components/server-side-rendering)). |

```sh
npm install @mykulyak/apigenie-docs
```

```html
<script type="module">
	import "@mykulyak/apigenie-docs";
</script>

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

## Elements

`<apg-api-reference>` renders a whole reference and picks the elements of the document's standard
by itself. The other elements show one part of a document each, for a page of your own design.

### [apg-api-reference and apg-spec](/docs/reference/doc-components/reference-and-spec)

| Element | What it shows |
| --- | --- |
| [`<apg-api-reference>`](/docs/reference/doc-components/reference-and-spec#apg-api-reference) | An API reference: navigation with search, overview, servers, authentication, operations grouped by tag with Try it out, and schemas. |
| [`<apg-spec>`](/docs/reference/doc-components/reference-and-spec#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. |
| [`<apg-nav>`](/docs/reference/doc-components/reference-and-spec#apg-nav) | Navigation: operations grouped by tag, webhooks and schemas, with search. |
| [`<apg-changelog>`](/docs/reference/doc-components/reference-and-spec#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"`). |

### [OpenAPI elements](/docs/reference/doc-components/openapi)

| Element | What it shows |
| --- | --- |
| [`<apg-overview>`](/docs/reference/doc-components/openapi#apg-overview) | Title, version, description, contact, license and external documentation of the API. |
| [`<apg-operation>`](/docs/reference/doc-components/openapi#apg-operation) | Documentation of one operation: parameters, request body, responses (with examples and schemas), security and callbacks, with an optional embedded Try it out. |
| [`<apg-schema>`](/docs/reference/doc-components/openapi#apg-schema) | Schema as an expandable tree: properties, items, combinators, constraints, enums, defaults and examples. |
| [`<apg-try-it>`](/docs/reference/doc-components/openapi#apg-try-it) | Sends requests to the API: parameters, request body (text, forms, file uploads), server and credentials, with a live URL preview, code samples and a response viewer that streams server-sent events and NDJSON. |
| [`<apg-auth>`](/docs/reference/doc-components/openapi#apg-auth) | Credentials for the API's security schemes: API keys, HTTP Basic and Bearer, OAuth 2.0 flows (authorization code with PKCE, client credentials, implicit, password) and OpenID Connect discovery. |
| [`<apg-servers>`](/docs/reference/doc-components/openapi#apg-servers) | Chooses the server Try it out sends requests to: a declared server with its variables, or a custom URL. |
| [`<apg-code-samples>`](/docs/reference/doc-components/openapi#apg-code-samples) | Code samples for a request: curl, JavaScript (fetch) and Python (requests). |

### [Swagger 2.0 elements](/docs/reference/doc-components/swagger)

| Element | What it shows |
| --- | --- |
| [`<apg-swagger-overview>`](/docs/reference/doc-components/swagger#apg-swagger-overview) | Title, version, description, contact, license and external documentation of a Swagger 2.0 API. |
| [`<apg-swagger-hosts>`](/docs/reference/doc-components/swagger#apg-swagger-hosts) | Where a Swagger 2.0 API is served: `host`, `basePath` and `schemes`, the resulting base URLs, and the media types the API consumes and produces. |
| [`<apg-swagger-security>`](/docs/reference/doc-components/swagger#apg-swagger-security) | The security definitions of a Swagger 2.0 document: type, where API keys go, OAuth 2.0 flow, URLs and scopes, and the requirements that apply to every operation. |
| [`<apg-swagger-operation>`](/docs/reference/doc-components/swagger#apg-swagger-operation) | Documentation of one operation of a Swagger 2.0 document: the media types it consumes and produces, path, query, header and form parameters, the body parameter, responses with their headers, examples and schemas, and security, with an optional embedded Try it out. |

### [AsyncAPI elements](/docs/reference/doc-components/asyncapi)

| Element | What it shows |
| --- | --- |
| [`<apg-asyncapi-overview>`](/docs/reference/doc-components/asyncapi#apg-asyncapi-overview) | Title, version, description, contact, license, tags and external documentation of an AsyncAPI 3 document, with its `id` and default content type. |
| [`<apg-asyncapi-servers>`](/docs/reference/doc-components/asyncapi#apg-asyncapi-servers) | The servers of an AsyncAPI document (or the one named by `server`): protocol, URL, variables, security, the channels available on it and its bindings. |
| [`<apg-asyncapi-security>`](/docs/reference/doc-components/asyncapi#apg-asyncapi-security) | The security schemes of an AsyncAPI document (`components.securitySchemes`): type, what it asks for, where API keys go, OAuth 2.0 flows with their URLs and scopes, OpenID Connect discovery. |
| [`<apg-asyncapi-operation>`](/docs/reference/doc-components/asyncapi#apg-asyncapi-operation) | One operation of an AsyncAPI document: its action (send or receive), channel and address, the messages with their headers, payloads and examples, the reply of request/reply operations, security, traits and bindings. |
| [`<apg-asyncapi-channel>`](/docs/reference/doc-components/asyncapi#apg-asyncapi-channel) | One channel of an AsyncAPI document: its address with parameters, the servers it is on, its messages, the operations on it, and its bindings. |
| [`<apg-asyncapi-message>`](/docs/reference/doc-components/asyncapi#apg-asyncapi-message) | One message of an AsyncAPI document: content type, headers and payload (schema trees, or the schema as written for formats such as Avro and Protobuf), examples, correlation ID, bindings, and the channels and operations using it. |
| [`<apg-asyncapi-bindings>`](/docs/reference/doc-components/asyncapi#apg-asyncapi-bindings) | The protocol bindings of an AsyncAPI server, channel, operation or message, given as the `bindings` of their view: one block per protocol with its `bindingVersion` and fields. |

### [Protobuf and gRPC elements](/docs/reference/doc-components/protobuf)

| Element | What it shows |
| --- | --- |
| [`<apg-protobuf-overview>`](/docs/reference/doc-components/protobuf#apg-protobuf-overview) | The package, file, syntax, header comment, imports and file options of a Protobuf file. |
| [`<apg-protobuf-service>`](/docs/reference/doc-components/protobuf#apg-protobuf-service) | A gRPC service of a Protobuf file: its description, options and methods, each with its streaming kind, request and response. |
| [`<apg-protobuf-method>`](/docs/reference/doc-components/protobuf#apg-protobuf-method) | A gRPC method: its streaming kind, HTTP/2 path, request and response messages (with their fields), HTTP/JSON transcoding rules (`google.api.http`), JSON examples of both messages and code samples. |
| [`<apg-protobuf-message>`](/docs/reference/doc-components/protobuf#apg-protobuf-message) | A message of a Protobuf file: its fields (number, name and JSON name, type, label, oneof, options, comment), oneofs, reserved numbers and names, nested types, the methods using it and an example in the proto3 JSON form. |
| [`<apg-protobuf-enum>`](/docs/reference/doc-components/protobuf#apg-protobuf-enum) | An enum of a Protobuf file: its values (name, number, comment, deprecation), reserved numbers and names, and options. |
| [`<apg-grpc-code-samples>`](/docs/reference/doc-components/protobuf#apg-grpc-code-samples) | Code samples calling a gRPC method with its example request: grpcurl, Node.js (`@grpc/grpc-js`), Python (`grpcio`) and Go, in the form each takes for the method's streaming kind. |

### [GraphQL elements](/docs/reference/doc-components/graphql)

| Element | What it shows |
| --- | --- |
| [`<apg-graphql-overview>`](/docs/reference/doc-components/graphql#apg-graphql-overview) | The description of a GraphQL schema, its file, root operation types, size and schema directives. |
| [`<apg-graphql-operation>`](/docs/reference/doc-components/graphql#apg-graphql-operation) | A GraphQL operation, that is a field of a root operation type (`Query.books`): its arguments, the type it returns (with its fields), an example operation with variables and a response, code samples and Try it out. |
| [`<apg-graphql-type>`](/docs/reference/doc-components/graphql#apg-graphql-type) | A type of a GraphQL schema: object and interface types with their fields (and the fields' arguments), input types with their fields and default values, enums with their values, unions with their members, and scalars; the interfaces a type implements, the types implementing an interface, the unions an object belongs to, where the type is used, and an example value of input types. |
| [`<apg-graphql-directive>`](/docs/reference/doc-components/graphql#apg-graphql-directive) | A directive definition of a GraphQL schema: its arguments, where it may be used and whether it is repeatable. |
| [`<apg-graphql-code-samples>`](/docs/reference/doc-components/graphql#apg-graphql-code-samples) | Code samples sending a GraphQL operation with its example variables: curl, JavaScript (`fetch`) and Python (`requests`), each posting `{query, variables, operationName}` as JSON. |
| [`<apg-graphql-try-it>`](/docs/reference/doc-components/graphql#apg-graphql-try-it) | Sends a GraphQL operation to an endpoint: the operation (prefilled with the example), its variables and headers, posted as JSON. |

### [Building blocks](/docs/reference/doc-components/building-blocks)

| Element | What it shows |
| --- | --- |
| [`<apg-markdown>`](/docs/reference/doc-components/building-blocks#apg-markdown) | CommonMark/GFM from the document, sanitized: raw HTML is shown as text, links are limited to http(s)/mailto and open in a new tab, and `#/components/schemas/X` links go to the schema page. |
| [`<apg-code-block>`](/docs/reference/doc-components/building-blocks#apg-code-block) | Code with a copy button. |
| [`<apg-method-badge>`](/docs/reference/doc-components/building-blocks#apg-method-badge) | HTTP method label, the action of an AsyncAPI operation (`send`, `receive`), the streaming kind of a gRPC method (`unary`, `server-stream`, `client-stream`, `bidi`), or the kind of a GraphQL operation (`query`, `mutation`, `subscription`). |

An element given a kind of document it does not show (an OpenAPI element given a Swagger 2.0 or
AsyncAPI document, and so on) shows a notice naming the element to use instead, or saying that
there is none: `<apg-try-it>`, `<apg-auth>`, `<apg-servers>` and `<apg-code-samples>` are for
OpenAPI and Swagger 2.0 documents.

## Where the document comes from

The elements that show part of a document have these attributes and properties. They take the
document from the first of `api`, `spec` and `spec-url` that is set, and otherwise from the
enclosing `<apg-spec>` or `<apg-api-reference>`:

| Attribute or property | |
| --- | --- |
| `api` (property) | An `ApiContext` shared explicitly. Composite elements pass theirs to their parts. |
| `spec` (property) | The document as YAML or JSON text, `.proto` or GraphQL text, or a parsed value. |
| `spec-url` | A URL. Elements naming the same URL share one context: the document is fetched and parsed once, and the server choice, the credentials and the Try it out input are shared by every element of the page. |
| `theme` | `light` or `dark`; by default the page's `color-scheme` decides. |

`<apg-code-block>`, `<apg-method-badge>` and `<apg-asyncapi-bindings>` show what they are given and
have none of these.

`<apg-spec>` and `<apg-api-reference>` also read a child
`<script type="application/yaml" data-spec>` (or `application/json`), for a CMS where the
document is pasted into the page.

## WebAssembly modules

AsyncAPI documents, `.proto` files and GraphQL schemas are read by WebAssembly modules built from
the same parsers as the `apigenie` CLI. They are in the package's `dist/wasm/`, and the page loads
one when it shows a document of its standard:

| Standard | Module | Attribute on `<apg-spec>` and `<apg-api-reference>` | For every element |
| --- | --- | --- | --- |
| AsyncAPI | `asyncapi.web.mjs`, `asyncapi.web.wasm` | `asyncapi-wasm-url` | `configureAsyncApiEngine(url)` |
| Protobuf | `protobuf.web.mjs`, `protobuf.web.wasm` | `protobuf-wasm-url` | `configureProtobufEngine(url)` |
| GraphQL | `graphql.web.mjs`, `graphql.web.wasm` | `graphql-wasm-url` | `configureGraphQLEngine(url)` |

There is no JavaScript reader of these standards to fall back on: without its module, a document
fails to load. The documentation model the module writes (`{"apigenieAsyncAPI": 1, …}`,
`{"apigenieProtobuf": 1, …}`, `{"apigenieGraphQL": 1, …}`), which a docs bundle holds, can be
given instead of the text and needs no module. OpenAPI and Swagger 2.0 documents are read in
JavaScript.

## Frameworks

| Framework | What it needs |
| --- | --- |
| Plain HTML, a CMS | The `<script type="module">` tag; the document inline in a `<script type="application/yaml" data-spec>` child when there is no URL for it. |
| React 19 | Nothing: properties such as `spec` and events such as `onapg-request` work natively. React 18 sets properties through a `ref`. |
| Vue | `compilerOptions.isCustomElement = (tag) => tag.startsWith("apg-")`, then `<apg-operation :spec="doc" operation-id="getPet" />`. |
| Svelte | Nothing: `<apg-spec spec-url="/openapi.yaml">`. |
| Angular | `CUSTOM_ELEMENTS_SCHEMA` on the component or the module. |

TypeScript knows the elements (`HTMLElementTagNameMap`) and their events (`HTMLElementEventMap`).
The package's `custom-elements.json` lists every attribute, property, event, slot, CSS part and
CSS custom property, for editors and framework type generators; the pages of this reference are
written from it.

## Limitations

- OpenAPI 3.0 and 3.1, Swagger 2.0, AsyncAPI 3.0 and 3.1 and proto3 only. OpenAPI 3.2, Swagger
  1.x, AsyncAPI 2.x, proto2 and editions are reported as unsupported.
- Only references within the document are resolved: bundle a document of several files first
  (`apigenie bundle`).
- Large YAML documents are parsed on the main thread.
- The WebAssembly parser engine (`parserEngine`) reads OpenAPI documents; Swagger 2.0 documents
  always use the JavaScript one.
- In Try it out, a `collectionFormat` other than `csv` on path and header parameters of a
  Swagger 2.0 document is sent comma-separated.
- AsyncAPI documents are documentation only: there is no Try it out for brokers. Bindings are
  listed as written, not explained per protocol, and schemas in formats other than JSON Schema
  (Avro, Protobuf, RAML) are shown as written.
- Protobuf files are documentation only as well: browsers cannot call gRPC services, and the code
  samples show how to. One file is documented at a time, with the standard imports; extensions
  (`extend`) are not listed.
- GraphQL schemas are read from SDL only, not from introspection results, one file at a time. Try
  it out sends queries and mutations over HTTP, not subscriptions over WebSocket or SSE.