# GraphQL elements

Source: https://apigenie.pl/docs/reference/doc-components/graphql
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), [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), [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 GraphQL schemas (SDL). Operations, the fields of the root operation types, are
named by schema coordinate (`Query.books`), by kind and field (`mutation.borrow`) or by field
(`books`); types and directives by name.

GraphQL text is read by the graphql WebAssembly module (`graphql.web.mjs` and `graphql.web.wasm`):
give its URL with `graphql-wasm-url` on `<apg-spec>` or `<apg-api-reference>`, or to every element
with `configureGraphQLEngine(url)`. Type extensions are merged into their types, rules the schema
breaks are listed as problems, and undefined types are shown unresolved. The documentation model
(`{"apigenieGraphQL": 1, …}`) can be given instead and needs no module.

Operations are sent to `graphql-endpoint`, by default `/graphql` on the origin of the document.
The proxy, the interceptors and the `apg-request` and `apg-response` events of
[Try it out](/docs/reference/doc-components/try-it-out) apply.

```html
<apg-spec spec-url="/schema.graphql" graphql-wasm-url="/wasm/graphql.web.mjs" graphql-endpoint="https://api.example.com/graphql">
	<apg-graphql-overview></apg-graphql-overview>
	<apg-graphql-operation name="Query.books"></apg-graphql-operation>
	<apg-graphql-type name="Book"></apg-graphql-type>
</apg-spec>
```

## `<apg-graphql-overview>`

The description of a GraphQL schema, its file, root operation types, size and schema
directives.

Loaded on its own with `import "@mykulyak/apigenie-docs/components/apg-graphql-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 title: the heading the schema description starts with, or the file name (`h1` unless `heading-level` says otherwise). |
| `info` | The file line. |
| `roots` | The root operation types. |
| `type-link` | Links to the root types. |
| `directive-link` | Links to the definitions of the schema's directives. |

Forwarded from the elements inside it:

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

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

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

### Attributes

| Attribute | Property | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `name` | `name` | `string` |  | The operation: its schema coordinate (`Query.books`), kind and field (`mutation.borrow`) or field (`books`). |
| `heading-level` | `headingLevel` | `number` | `2` | Level of the title heading. |
| `endpoint` | `endpoint` | `string` |  | The endpoint the code samples post to; by default the one of Try it out. |
| `hide-samples` | `hideSamples` | `boolean` | `false` | Hide the code samples. |
| `hide-try-it` | `hideTryIt` | `boolean` | `false` | Hide Try it out. |
| `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. |

### CSS parts

| Part | Description |
| --- | --- |
| `operation` | The container. |
| `header` | The header with the name and badges. |
| `title` | The name of the field. |
| `coordinate` | The schema coordinate (`Query.books`). |
| `summary` | The summary line, when the field has no description of its own. |
| `badge` | Badges (deprecated). |
| `section` | Sections (arguments, response, example, code samples, try it out). |
| `section-title` | Section headings. |
| `arguments` | The table of arguments. |
| `argument` | An argument's row. |
| `type-link` | Links to type pages. |
| `directive-link` | Links to directive definitions. |

Forwarded from the elements inside it:

- [`<apg-markdown>`](/docs/reference/doc-components/building-blocks#apg-markdown): `markdown`
- [`<apg-method-badge>`](/docs/reference/doc-components/building-blocks#apg-method-badge): `method`
- [`<apg-graphql-type>`](/docs/reference/doc-components/graphql#apg-graphql-type): `type`, `kind`, `fields`, `field`, `values`, `operation-link`
- [`<apg-code-block>`](/docs/reference/doc-components/building-blocks#apg-code-block): `code-block`, `code`, `copy-button`
- [`<apg-graphql-code-samples>`](/docs/reference/doc-components/graphql#apg-graphql-code-samples): `code-samples`, `tab`, `tab-active`
- [`<apg-graphql-try-it>`](/docs/reference/doc-components/graphql#apg-graphql-try-it): `try-it`, `label`, `input`, `textarea`, `button`, `button-primary`, `problems`, `response`, `response-status`, `graphql-errors`, `cors`

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

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

### Attributes

| Attribute | Property | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `name` | `name` | `string` |  | The type, by name. |
| `heading-level` | `headingLevel` | `number` | `2` | Level of the title heading. |
| `embedded` | `embedded` | `boolean` | `false` | Shown inside an operation, whose heading names the type: its fields, values or members only. |

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 |
| --- | --- |
| `type` | The container. |
| `header` | The header with the name and badges. |
| `title` | The name. |
| `kind` | The kind of the type (`object`, `enum`…). |
| `badge` | Badges (root, deprecated). |
| `section` | Sections (fields, values, members, used by…). |
| `section-title` | Section headings. |
| `fields` | The table of fields (or input fields). |
| `field` | A field's row. |
| `arguments` | Tables of arguments. |
| `argument` | An argument's row. |
| `values` | The table of enum values. |
| `type-link` | Links to type pages. |
| `operation-link` | Links to operation pages (fields of root types). |
| `directive-link` | Links to directive definitions. |

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-method-badge>`](/docs/reference/doc-components/building-blocks#apg-method-badge): `method`

## `<apg-graphql-directive>`

A directive definition of a GraphQL schema: its arguments, where it may be used and whether it
is repeatable.

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

### Attributes

| Attribute | Property | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `name` | `name` | `string` |  | The directive, by name with or without `@`. |
| `heading-level` | `headingLevel` | `number` | `2` | Level of the title heading. |

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 |
| --- | --- |
| `directive` | The container. |
| `header` | The header with the name and badges. |
| `title` | The name (`@name`). |
| `badge` | Badges (repeatable). |
| `section` | Sections (arguments, locations). |
| `section-title` | Section headings. |
| `arguments` | The table of arguments. |
| `argument` | An argument's row. |
| `type-link` | Links to type pages. |
| `locations` | The list of locations. |

Forwarded from the elements inside it:

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

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

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

### Attributes

| Attribute | Property | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `operation` | `operation` | `string` |  | The operation: `Query.books`, `query.books` or `books`. |
| `endpoint` | `endpoint` | `string` |  | The endpoint the samples post to; by default the one of Try it out. |
| `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).

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

## `<apg-graphql-try-it>`

Sends a GraphQL operation to an endpoint: the operation (prefilled with the example), its
variables and headers, posted as JSON. The endpoint and headers are shared by every operation
of the schema. Subscriptions need a streaming transport and are not sent.

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-graphql-try-it";`.

### Attributes

| Attribute | Property | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `operation` | `operation` | `string` |  | The operation: `Query.books`, `query.books` or `books`. |

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. |
| `textarea` | The operation and variables editors. |
| `button` | Secondary buttons. |
| `button-primary` | The Send button. |
| `problems` | Problems that block the request. |
| `response` | The response viewer. |
| `response-status` | The response status code. |
| `graphql-errors` | The `errors` of the response. |
| `cors` | What a cross-origin request needs from the server, when it failed before a response. |

Forwarded from the elements inside it:

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