# apg-api-reference and apg-spec Source: https://apigenie.pl/docs/reference/doc-components/reference-and-spec Part of the reference of [@mykulyak/apigenie-docs](https://apigenie.pl/docs/reference/doc-components.md). Its other pages: [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). `` renders a whole reference from one tag: navigation with search, the overview, servers, authentication, the operations with Try it out, and the schemas. For an AsyncAPI document, a Protobuf file or a GraphQL schema it uses the elements of that standard. `` loads a document and shares it with the elements inside it, for a page of your own design. Both carry the settings of Try it out ([Try it out](/docs/reference/doc-components/try-it-out)). ## A page of your own from parts ```html

Quick start

 ``` Operations are selected with `operation-id`, or with `method` and `path`. The pages of [AsyncAPI](/docs/reference/doc-components/asyncapi), [Protobuf](/docs/reference/doc-components/protobuf) and [GraphQL](/docs/reference/doc-components/graphql) elements show the same page for their standards. ## Pages and routes With `layout="sidebar"`, the default, `` shows one page at a time and keeps it in the URL as `routing` says: | `routing` | The URL of an operation's page | | --- | --- | | `hash` (default) | `#/operation/getPet` | | `history` | `/operation/getPet`; the server must serve the reference's page for these paths. | | `none` | Unchanged; `route` names the page, as in server-side rendering. | `route` takes `operation/getPet`, `tag/pets` or `schema/Pet`; for AsyncAPI `channel/orders` or `message/orderCreated`; for Protobuf `service/LibraryService`, `method/LibraryService.GetBook`, `message/Book` or `enum/Genre`; for GraphQL `operation/query.books`, `type/Book` or `directive/auth`. `layout="single"` shows every page one after the other and scrolls to the target. Links between pages emit the cancelable `apg-navigate` event: cancel it to route with your application's router. ## `` An API reference: navigation with search, overview, servers, authentication, operations grouped by tag with Try it out, and schemas. It is built from the public parts (``, ``, …) and forwards their CSS parts. Swagger 2.0 documents are shown with the `apg-swagger-*` parts (overview, hosts, security definitions, operations) and their schemas are called definitions. AsyncAPI 3 documents are shown with the `apg-asyncapi-*` parts: overview, servers and security schemes, then pages for operations, channels, messages and schemas. Protobuf files are shown with the `apg-protobuf-*` parts: an overview with the services, then pages for services, gRPC methods, messages and enums. GraphQL schemas are shown with the `apg-graphql-*` parts: an overview with the queries, mutations and subscriptions, then pages for operations (with Try it out), types and directives. Loaded on its own with `import "@mykulyak/apigenie-docs/components/apg-api-reference";`. ### Attributes | Attribute | Property | Type | Default | Description | | --- | --- | --- | --- | --- | | `layout` | `layout` | `"sidebar" \| "single"` | `"sidebar"` | `sidebar` (one page at a time) or `single` (everything on one page). | | `routing` | `routing` | `RoutingMode` | `"hash"` | How the current page is kept in the URL: `hash`, `history` or `none`. | | `base-path` | `basePath` | `string` | `"/"` | With `routing="history"`: the path the reference is mounted at, such as `/docs`. | | `route` | `route` | `string` | | Page to show, such as `operation/getPet` (used by server-side rendering and with `routing="none"`). | | `hide-try-it` | `hideTryIt` | `boolean` | `false` | Hides Try it out, and the server and credential choices it needs. | | `hide-schemas` | `hideSchemas` | `boolean` | `false` | Hides the schemas (definitions in Swagger 2.0) from the overview and the navigation. | | `show-problems` | `showProblems` | `boolean` | `false` | Show problems found in the document (unresolved references, validation issues). | | `changelog-url` | `changelogUrl` | `string` | | URL of the changelog of a docs bundle (`changelog.json`), fetched in the browser; adds the Changelog page. | | `proxy-url` | `proxyUrl` | `string` | | CORS proxy: `https://proxy.example/?url={url}`, or a prefix the request URL is appended to. | | `credentials` | `credentials` | `RequestCredentials` | `"same-origin"` | Credentials mode of Try-it-out requests: `omit`, `same-origin` or `include`. | | `timeout` | `timeout` | `number` | `30000` | Try-it-out timeout in milliseconds. | | `max-response-bytes` | `maxResponseBytes` | `number` | `5242880` | Response bodies larger than this many bytes (5 MiB) are truncated. | | `persist-auth` | `persistAuth` | `PersistMode` | | Keep credentials across page loads: `session` or `local` storage (default: memory only). | | `oauth2-redirect-url` | `oauth2RedirectUrl` | `string` | | Redirect page registered with the OAuth 2.0 authorization server. | | `oauth2-client-id` | `oauth2ClientId` | `string` | | OAuth 2.0 client ID used by every OAuth 2.0 / OpenID Connect scheme without its own `authConfig`. | | `schema-depth` | `schemaDepth` | `number` | `6` | Levels of referenced schemas expanded inline. | | `asyncapi-wasm-url` | `asyncapiWasmUrl` | `string` | | URL of the asyncapi WebAssembly module (`asyncapi.web.mjs`, with `asyncapi.web.wasm` next to it), which reads AsyncAPI documents; loaded when one is shown. | | `protobuf-wasm-url` | `protobufWasmUrl` | `string` | | URL of the protobuf WebAssembly module (`protobuf.web.mjs`, with `protobuf.web.wasm` next to it), which reads .proto documents; loaded when one is shown. | | `graphql-wasm-url` | `graphqlWasmUrl` | `string` | | URL of the graphql WebAssembly module (`graphql.web.mjs`, with `graphql.web.wasm` next to it), which reads GraphQL schemas; loaded when one is shown. | | `graphql-endpoint` | `graphqlEndpoint` | `string` | | The URL GraphQL operations are sent to (default: `/graphql` on the origin of the document). | And `spec-url`, `spec`, `api` and `theme`, like every element that shows a document: [Where the document comes from](/docs/reference/doc-components#where-the-document-comes-from). ### Properties | Property | Type | Description | | --- | --- | --- | | `changelog` | `ChangelogFile` | The changelog of a docs bundle, as a value; adds the Changelog page. | | `examples` | `ExampleFile[]` | The example files of a docs bundle, shown on the overview or on the operation they are named after. | | `locales` | `LocaleLink[]` | The same page in other languages (a docs bundle with several locales): the locale switcher of the sidebar. | | `authConfig` | `Record` | OAuth 2.0 client settings per security scheme. | | `fetch` | `typeof fetch` | `fetch` used by Try it out (for example to add tracing). | | `requestInterceptor` | `ApiSettings["requestInterceptor"]` | Called with every Try-it-out request before it is sent. | | `responseInterceptor` | `ApiSettings["responseInterceptor"]` | Called with every Try-it-out response. | | `parserEngine` | `ParserEngine` | Parser of documents given as text (default: the JavaScript parser). | | `asyncapiEngine` | `AsyncApiEngine` | Reads AsyncAPI documents (instead of `asyncapi-wasm-url`). | | `protobufEngine` | `ProtobufEngine` | Reads .proto documents (instead of `protobuf-wasm-url`). | | `graphqlEngine` | `GraphQLEngine` | Reads GraphQL schemas (instead of `graphql-wasm-url`). | ### Methods | Method | Description | | --- | --- | | `navigate(route)` | Shows a page (and records it in the URL unless `routing="none"`). | ### Events | Event | Description | | --- | --- | | `apg-navigate` | A link was followed; cancel it to route yourself. | | `apg-spec-load` | The document was parsed. | | `apg-spec-error` | The document could not be loaded or parsed. | ### Slots | Slot | Description | | --- | --- | | `logo` | Shown at the top of the sidebar. | | `header` | Shown above the content. | | `intro` | Shown on the overview page, before the API description. | | `footer` | Shown after the content. | ### CSS parts | Part | Description | | --- | --- | | `reference` | The layout grid. | | `sidebar` | The sidebar. | | `content` | The main content. | | `menu-button` | Opens the sidebar on narrow screens. | | `page-title` | Headings of tag and schema pages. | | `problems` | The problems panel (`show-problems`). | | `operation-link` | Operation links in the overview's index. | | `channel-link` | Channel links in the overview's index (AsyncAPI). | | `message-link` | Message links in the overview's index (AsyncAPI, Protobuf). | | `service-link` | Service links in the overview's index (Protobuf). | | `method-link` | Method links in the overview's index (Protobuf). | | `enum-link` | Enum links in the overview's index (Protobuf). | | `type-link` | Type links in the overview's index (GraphQL). | | `directive-link` | Directive links in the overview's index (GraphQL). | | `section-title` | Headings of the overview's sections (servers, authentication, operations, …). | | `address` | Channel addresses in the overview's index (AsyncAPI). | | `locales` | The language switcher, when the reference has `locales`. | | `locale` | One language in it. | | `examples` | The example files of the overview or of a GraphQL operation (`examples`). | | `example-title` | The name of an example file, with its download link. | Forwarded from the elements inside it: - [``](/docs/reference/doc-components/reference-and-spec#apg-nav): `nav`, `search`, `nav-group`, `nav-group-title`, `nav-item`, `nav-item-active` - [``](/docs/reference/doc-components/building-blocks#apg-method-badge): `method` - [``](/docs/reference/doc-components/openapi#apg-overview): `overview`, `title`, `version`, `info`, `link` - [``](/docs/reference/doc-components/building-blocks#apg-markdown): `markdown` - [``](/docs/reference/doc-components/openapi#apg-servers): `servers`, `label`, `select`, `input`, `url` - [``](/docs/reference/doc-components/openapi#apg-auth): `auth`, `scheme`, `scheme-name`, `status`, `button`, `button-primary` - [``](/docs/reference/doc-components/openapi#apg-operation): `operation`, `header`, `path`, `summary`, `section`, `table`, `parameter-name`, `type`, `required`, `tab`, `tab-active`, `badge`, `tag-link`, `response`, `response-status`, `try-it-button` - [``](/docs/reference/doc-components/openapi#apg-schema): `schema`, `schema-row`, `property-name`, `toggle`, `ref-link`, `format-link`, `constraint` - [``](/docs/reference/doc-components/building-blocks#apg-code-block): `code-block`, `code`, `copy-button` - [``](/docs/reference/doc-components/openapi#apg-try-it): `try-it`, `textarea`, `cors` - [``](/docs/reference/doc-components/openapi#apg-code-samples): `code-samples` - [``](/docs/reference/doc-components/swagger#apg-swagger-hosts): `hosts` - [``](/docs/reference/doc-components/swagger#apg-swagger-security): `security` - [``](/docs/reference/doc-components/swagger#apg-swagger-operation): `media-types` - [``](/docs/reference/doc-components/asyncapi#apg-asyncapi-servers): `server`, `server-name`, `protocol` - [``](/docs/reference/doc-components/asyncapi#apg-asyncapi-bindings): `bindings`, `binding`, `binding-protocol` - [``](/docs/reference/doc-components/asyncapi#apg-asyncapi-channel): `channel` - [``](/docs/reference/doc-components/asyncapi#apg-asyncapi-message): `message`, `content-type` - [``](/docs/reference/doc-components/protobuf#apg-protobuf-overview): `options` - [``](/docs/reference/doc-components/protobuf#apg-protobuf-service): `service`, `full-name` - [``](/docs/reference/doc-components/protobuf#apg-protobuf-method): `grpc-path`, `http-rules` - [``](/docs/reference/doc-components/protobuf#apg-protobuf-message): `fields`, `field` - [``](/docs/reference/doc-components/protobuf#apg-protobuf-enum): `enum`, `values`, `value` - [``](/docs/reference/doc-components/graphql#apg-graphql-overview): `roots` - [``](/docs/reference/doc-components/graphql#apg-graphql-operation): `coordinate`, `arguments`, `argument` - [``](/docs/reference/doc-components/graphql#apg-graphql-type): `kind` - [``](/docs/reference/doc-components/graphql#apg-graphql-try-it): `graphql-errors` - [``](/docs/reference/doc-components/graphql#apg-graphql-directive): `directive`, `locations` - [``](/docs/reference/doc-components/reference-and-spec#apg-changelog): `changelog`, `entry`, `revision`, `item`, `item-link`, `history` ### CSS custom properties | Property | Description | | --- | --- | | `--apg-sidebar-width` | Width of the sidebar. | | `--apg-content-width` | Maximum width of the content. | | `--apg-sticky-top` | Offset of the sticky sidebar (height of a fixed page header). | ## `` 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. It renders nothing but its content. The document comes from `spec-url`, the `spec` property or a child `` (for a CMS). The Try-it-out settings (`proxy-url`, `credentials`, `persist-auth`, `authConfig`, …) apply to every element inside. Loaded on its own with `import "@mykulyak/apigenie-docs/components/apg-spec";`. ### Attributes | Attribute | Property | Type | Default | Description | | --- | --- | --- | --- | --- | | `proxy-url` | `proxyUrl` | `string` | | CORS proxy: `https://proxy.example/?url={url}`, or a prefix the request URL is appended to. | | `credentials` | `credentials` | `RequestCredentials` | `"same-origin"` | Credentials mode of Try-it-out requests: `omit`, `same-origin` or `include`. | | `timeout` | `timeout` | `number` | `30000` | Try-it-out timeout in milliseconds. | | `max-response-bytes` | `maxResponseBytes` | `number` | `5242880` | Response bodies larger than this many bytes (5 MiB) are truncated. | | `persist-auth` | `persistAuth` | `PersistMode` | | Keep credentials across page loads: `session` or `local` storage (default: memory only). | | `oauth2-redirect-url` | `oauth2RedirectUrl` | `string` | | Redirect page registered with the OAuth 2.0 authorization server. | | `oauth2-client-id` | `oauth2ClientId` | `string` | | OAuth 2.0 client ID used by every OAuth 2.0 / OpenID Connect scheme without its own `authConfig`. | | `schema-depth` | `schemaDepth` | `number` | `6` | Levels of referenced schemas expanded inline. | | `asyncapi-wasm-url` | `asyncapiWasmUrl` | `string` | | URL of the asyncapi WebAssembly module (`asyncapi.web.mjs`, with `asyncapi.web.wasm` next to it), which reads AsyncAPI documents; loaded when one is shown. | | `protobuf-wasm-url` | `protobufWasmUrl` | `string` | | URL of the protobuf WebAssembly module (`protobuf.web.mjs`, with `protobuf.web.wasm` next to it), which reads .proto documents; loaded when one is shown. | | `graphql-wasm-url` | `graphqlWasmUrl` | `string` | | URL of the graphql WebAssembly module (`graphql.web.mjs`, with `graphql.web.wasm` next to it), which reads GraphQL schemas; loaded when one is shown. | | `graphql-endpoint` | `graphqlEndpoint` | `string` | | The URL GraphQL operations are sent to (default: `/graphql` on the origin of the document). | And `spec-url`, `spec`, `api` and `theme`, like every element that shows a document: [Where the document comes from](/docs/reference/doc-components#where-the-document-comes-from). ### Properties | Property | Type | Description | | --- | --- | --- | | `authConfig` | `Record` | OAuth 2.0 client settings per security scheme. | | `fetch` | `typeof fetch` | `fetch` used by Try it out (for example to add tracing). | | `requestInterceptor` | `ApiSettings["requestInterceptor"]` | Called with every Try-it-out request before it is sent. | | `responseInterceptor` | `ApiSettings["responseInterceptor"]` | Called with every Try-it-out response. | | `parserEngine` | `ParserEngine` | Parser of documents given as text (default: the JavaScript parser). | | `asyncapiEngine` | `AsyncApiEngine` | Reads AsyncAPI documents (instead of `asyncapi-wasm-url`). | | `protobufEngine` | `ProtobufEngine` | Reads .proto documents (instead of `protobuf-wasm-url`). | | `graphqlEngine` | `GraphQLEngine` | Reads GraphQL schemas (instead of `graphql-wasm-url`). | ### Events | Event | Description | | --- | --- | | `apg-spec-load` | The document was parsed. | | `apg-spec-error` | The document could not be loaded or parsed. | ### Slots | Slot | Description | | --- | --- | | (default) | Components and any other content. | ## `` Navigation: operations grouped by tag, webhooks and schemas, with search. For AsyncAPI documents: operations, channels, messages and schemas. For Protobuf files: services with their methods, messages and enums. A document of a docs bundle with a changelog gets a Changelog item. Loaded on its own with `import "@mykulyak/apigenie-docs/components/apg-nav";`. ### Attributes | Attribute | Property | Type | Default | Description | | --- | --- | --- | --- | --- | | `filter` | `filter` | `string` | `""` | Initial search text. | | `hide-search` | `hideSearch` | `boolean` | `false` | Hides the search input. | | `hide-schemas` | `hideSchemas` | `boolean` | `false` | Leaves the schemas out of the navigation. | And `spec-url`, `spec`, `api` and `theme`, like every element that shows a document: [Where the document comes from](/docs/reference/doc-components#where-the-document-comes-from). ### Properties | Property | Type | Description | | --- | --- | --- | | `route` | `Route` | The page shown, highlighted in the list. | ### Events | Event | Description | | --- | --- | | `apg-navigate` | A link was followed; cancelable. | ### CSS parts | Part | Description | | --- | --- | | `nav` | The `