# OpenAPI elements

Source: https://apigenie.pl/docs/reference/doc-components/openapi
Part of the reference of [@mykulyak/apigenie-docs](https://apigenie.pl/docs/reference/doc-components.md).
Its other pages: [apg-api-reference and apg-spec](https://apigenie.pl/docs/reference/doc-components/reference-and-spec.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 elements of OpenAPI 3.0 and 3.1 documents. `<apg-nav>`, `<apg-schema>`, `<apg-try-it>`,
`<apg-auth>`, `<apg-servers>` and `<apg-code-samples>` show Swagger 2.0 documents as well;
[Swagger 2.0 elements](/docs/reference/doc-components/swagger) lists the elements of their own.

Operations are selected with `operation-id`, or with `method` and `path`; schemas with `name` (in
`components.schemas`) or `pointer`.

## `<apg-overview>`

Title, version, description, contact, license and external documentation of the API.

Loaded on its own with `import "@mykulyak/apigenie-docs/components/apg-overview";`.

### Attributes

| Attribute | Property | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `heading-level` | `headingLevel` | `number` | `1` | Level of the title heading (1–6). |

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).

### CSS parts

| Part | Description |
| --- | --- |
| `overview` | The container. |
| `title` | The API title (`h1` unless `heading-level` says otherwise). |
| `version` | Version badges. |
| `info` | Contact, license and terms line. |
| `link` | Links in the info line. |

Forwarded from the elements inside it:

- [`<apg-markdown>`](/docs/reference/doc-components/building-blocks#apg-markdown): `markdown`

## `<apg-operation>`

Documentation of one operation: parameters, request body, responses (with examples and
schemas), security and callbacks, with an optional embedded Try it out.

Loaded on its own with `import "@mykulyak/apigenie-docs/components/apg-operation";`.

### Attributes

| Attribute | Property | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `operation-id` | `operationId` | `string` |  | The operation, by `operationId`. |
| `method` | `method` | `string` |  | The operation by method and path (alternative to `operation-id`). |
| `path` | `path` | `string` |  | The path of the operation, with `method`. |
| `pointer` | `pointer` | `string` |  | The operation by JSON pointer. |
| `try-it` | `tryIt` | `"inline" \| "open" \| "none"` | `"inline"` | `inline`: a button shows Try it out; `open`: shown from the start; `none`: hidden. |
| `heading-level` | `headingLevel` | `number` | `2` | Level of the path heading. |
| `lazy` | `lazy` | `boolean` | `false` | Render only the header until the operation comes near the viewport (used for long pages; the full content is always rendered on the server). |

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).

### Methods

| Method | Description |
| --- | --- |
| `reveal()` | Renders the full content of a lazy operation. |

### Events

| Event | Description |
| --- | --- |
| `apg-navigate` | A tag link was followed; cancelable. |

### Slots

| Slot | Description |
| --- | --- |
| `before` | Content shown after the header. |
| `after` | Content shown at the end. |

### CSS parts

| Part | Description |
| --- | --- |
| `operation` | The container. |
| `header` | The header with method, path and summary. |
| `path` | The path. |
| `summary` | The summary line. |
| `section` | Sections (parameters, body, responses). |
| `section-title` | Section headings. |
| `table` | Tables. |
| `parameter-name` | Parameter names. |
| `type` | Type labels of parameters and headers. |
| `required` | Required markers. |
| `select` | The media type and example choices. |
| `tab` | Example and schema tabs; the selected one also has `tab-active`. |
| `tab-active` | The selected tab. |
| `badge` | Badges (deprecated, webhook). |
| `tag-link` | Links to tag pages. |
| `response` | One response. |
| `response-status` | Its status code. |
| `try-it-button` | The button that shows Try it out. |

Forwarded from the elements inside it:

- [`<apg-method-badge>`](/docs/reference/doc-components/building-blocks#apg-method-badge): `method`
- [`<apg-markdown>`](/docs/reference/doc-components/building-blocks#apg-markdown): `markdown`
- [`<apg-schema>`](/docs/reference/doc-components/openapi#apg-schema): `schema`, `schema-row`, `property-name`, `toggle`, `ref-link`, `format-link`, `constraint`
- [`<apg-code-block>`](/docs/reference/doc-components/building-blocks#apg-code-block): `code-block`, `code`, `copy-button`
- [`<apg-try-it>`](/docs/reference/doc-components/openapi#apg-try-it): `try-it`, `label`, `input`, `textarea`, `button`, `button-primary`, `url`, `problems`, `cors`
- [`<apg-servers>`](/docs/reference/doc-components/openapi#apg-servers): `servers`
- [`<apg-auth>`](/docs/reference/doc-components/openapi#apg-auth): `auth`, `scheme`, `scheme-name`, `status`
- [`<apg-code-samples>`](/docs/reference/doc-components/openapi#apg-code-samples): `code-samples`

## `<apg-schema>`

Schema as an expandable tree: properties, items, combinators, constraints, enums, defaults and
examples. Referenced schemas beyond the inline depth and recursive references expand on click.

Loaded on its own with `import "@mykulyak/apigenie-docs/components/apg-schema";`.

### Attributes

| Attribute | Property | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `name` | `name` | `string` |  | Name of a schema in `components.schemas`. |
| `pointer` | `pointer` | `string` |  | JSON pointer of the schema (alternative to `name`). |
| `depth` | `depth` | `number` | `1` | Levels of properties shown initially (1: the schema's own properties). |
| `with-example` | `withExample` | `boolean` | `false` | Show Schema / Example tabs with an example generated from the schema. |
| `hide-description` | `hideDescription` | `boolean` | `false` | Hide the root description (when the surrounding page shows it). |

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 |
| --- | --- | --- |
| `node` | `SchemaNode` | A schema view model to render directly (used by `<apg-operation>`). |

### Events

| Event | Description |
| --- | --- |
| `apg-navigate` | A schema link was followed; cancelable. |

### CSS parts

| Part | Description |
| --- | --- |
| `schema` | The tree. |
| `schema-row` | One property line. |
| `property-name` | Property name. |
| `type` | Type label. |
| `required` | Required marker. |
| `toggle` | Expand/collapse button. |
| `ref-link` | Link to a component schema's page. |
| `format-link` | Link to the specification of a `format`. |
| `constraint` | Constraint or fact (enum, default, pattern, …). |
| `tab` | Schema and example tabs (`with-example`); the selected one also has `tab-active`. |
| `tab-active` | The selected tab. |

Forwarded from the elements inside it:

- [`<apg-markdown>`](/docs/reference/doc-components/building-blocks#apg-markdown): `markdown`
- [`<apg-code-block>`](/docs/reference/doc-components/building-blocks#apg-code-block): `code-block`, `code`, `copy-button`

## `<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.

Events: `apg-request` (cancelable; `detail.request` may be replaced) before sending and
`apg-response` afterwards.

Loaded on its own with `import "@mykulyak/apigenie-docs/components/apg-try-it";`.

### Attributes

| Attribute | Property | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `operation-id` | `operationId` | `string` |  | The operation, by `operationId`. |
| `method` | `method` | `string` |  | The operation by method and path (alternative to `operation-id`). |
| `path` | `path` | `string` |  | The path of the operation, with `method`. |
| `pointer` | `pointer` | `string` |  | The operation by JSON pointer (used by `<apg-operation>`). |
| `hide-samples` | `hideSamples` | `boolean` | `false` | Hide the code samples. |

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).

### Events

| Event | Description |
| --- | --- |
| `apg-request` | Before a request is sent; cancelable, `detail.request` may be replaced. |
| `apg-response` | After a response (or failure). |

### CSS parts

| Part | Description |
| --- | --- |
| `try-it` | The container. |
| `section-title` | Headings of the form's sections. |
| `label` | Field labels. |
| `input` | Text inputs. |
| `select` | Selects. |
| `textarea` | Body and JSON editors. |
| `button` | Secondary buttons. |
| `button-primary` | The Send button. |
| `url` | The request URL. |
| `problems` | Problems that block or affect the request. |
| `response` | The response viewer. |
| `response-status` | The response status code. |
| `cors` | What a cross-origin request needs from the server, when it failed before a response. |
| `tab` | Response tabs; the selected one also has `tab-active`. |
| `tab-active` | The selected tab. |

Forwarded from the elements inside it:

- [`<apg-method-badge>`](/docs/reference/doc-components/building-blocks#apg-method-badge): `method`
- [`<apg-servers>`](/docs/reference/doc-components/openapi#apg-servers): `servers`
- [`<apg-auth>`](/docs/reference/doc-components/openapi#apg-auth): `auth`, `scheme`, `scheme-name`, `status`
- [`<apg-markdown>`](/docs/reference/doc-components/building-blocks#apg-markdown): `markdown`
- [`<apg-code-samples>`](/docs/reference/doc-components/openapi#apg-code-samples): `code-samples`
- [`<apg-code-block>`](/docs/reference/doc-components/building-blocks#apg-code-block): `code-block`, `code`, `copy-button`

## `<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. A token can always be pasted instead of running a flow.

Loaded on its own with `import "@mykulyak/apigenie-docs/components/apg-auth";`.

### Attributes

| Attribute | Property | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `schemes` | `schemes` | `string` |  | Comma-separated scheme names to show; all schemes by default. |

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).

### Events

| Event | Description |
| --- | --- |
| `apg-auth-change` | Credentials of a scheme were set or cleared. |

### CSS parts

| Part | Description |
| --- | --- |
| `auth` | The container. |
| `scheme` | One security scheme. |
| `scheme-name` | The scheme's name. |
| `status` | Authorized / not authorized. |
| `label` | Field labels. |
| `input` | Inputs. |
| `select` | Flow selection. |
| `button` | Secondary buttons. |
| `button-primary` | Authorize buttons. |

Forwarded from the elements inside it:

- [`<apg-markdown>`](/docs/reference/doc-components/building-blocks#apg-markdown): `markdown`

## `<apg-servers>`

Chooses the server Try it out sends requests to: a declared server with its variables, or a
custom URL. The choice is shared by every component showing the same API.

Loaded on its own with `import "@mykulyak/apigenie-docs/components/apg-servers";`.

### Attributes

Only `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).

### CSS parts

| Part | Description |
| --- | --- |
| `servers` | The container. |
| `label` | Field labels. |
| `select` | The server list and enumerated variables. |
| `input` | Variable and custom URL inputs. |
| `url` | The resolved server URL. |

## `<apg-code-samples>`

Code samples for a request: curl, JavaScript (fetch) and Python (requests). Shows the
request of an operation's Try-it-out form (credentials masked), or `request` when set.

Loaded on its own with `import "@mykulyak/apigenie-docs/components/apg-code-samples";`.

### Attributes

| Attribute | Property | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `operation-id` | `operationId` | `string` |  | Operation whose Try-it-out request is shown (by `operationId`). |
| `method` | `method` | `string` |  | Operation by method and path (alternative to `operation-id`). |
| `path` | `path` | `string` |  | The path of the operation, with `method`. |
| `languages` | `languages` | `string` | `"curl,javascript,python"` | Comma-separated languages: `curl`, `javascript`, `python`. |

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 |
| --- | --- | --- |
| `request` | `BuiltRequest` | A request to show instead of an operation's. |

### CSS parts

| Part | Description |
| --- | --- |
| `code-samples` | The container. |
| `tab` | Language tabs; the selected one also has `tab-active`. |
| `tab-active` | The selected tab. |

Forwarded from the elements inside it:

- [`<apg-code-block>`](/docs/reference/doc-components/building-blocks#apg-code-block): `code-block`, `code`, `copy-button`